業務でドキュメントを作成するケースは多々ある
例：仕様書・設計書・提案書・メール・障害票．．．
ここでは各ドキュメント共通してありがちなアンチパターンをまとめてみました。
1. 表記がバイト表示・マイクロ秒表示
- プログラムが出した数値をありのままに表示するパターン
- ファイルサイズが100MB, 1GBあろうと、バイト表示にする
- 桁数が多い数値に、桁区切り（,）を入れない
- 時間を何でもマイクロ秒・ミリ秒にする（1/100万秒までの精度が必要？体感で分かる？）
- 桁数が多い＝精度が高い＝良い文書、ではなく、見る人が必要とする精度に切り上げることが重要（売上で１円単位まで出すことが無いのと同様）
悪い例
| No | ファイル名 | ファイルサイズ(byte) | 処理時間(秒) |
|---|---|---|---|
| 1 | test.doc | 38498551 | 4.384861 |
| 2 | test2.xls | 493594387 | 52.079572 |
| 3 | sample.ppt | 973450 | 0.569463 |
| 4 | hoge.pdf | 4687889 | 2.481845 |
ましな例
| No | ファイル名 | ファイルサイズ(MB) | 処理時間(秒) |
|---|---|---|---|
| 1 | test.doc | 36.7 | 4.3 |
| 2 | test2.xls | 470.7 | 52.0 |
| 3 | sample.ppt | 0.9 | 0.5 |
| 4 | hoge.pdf | 4.4 | 2.5 |
2. 全角・半角、正式名称・略称全部バラバラ
同一人物が作成しているにも関わらず、その日の気分なのか統一しないパターン
悪い例
- 全角・半角が混在
- 例：Microsoft と Ｍｉｃｒｏｓｏｆｔ
- 大文字・小文字が混在
- 例：Microsoft と MICROSOFT
- 正式名称・略称が混在
- 例：Microsoft と MS
- アルファベット・カタカナ混在
- 例：Microsoft と マイクロソフト
- 全て混在。。。
- 例：Microsoft, Ｍｉｃｒｏｓｏｆｔ, MICROSOFT, MS, マイクロソフト
- オレオレ略語
- 例：ソリューション事業部をソ事
- 例：Google DriveをGD
半角・全角、正式名称・略称が混在すると、以下のデメリットがあるので、統一すること。
- 単純に見づらい
- 同一のものを指しているのか判別しづらい
- 検索・置換にヒットせずに漏れる
略語を使用する場合は、初出時に一言書いておくと良い（逆に長い単語の場合、略語を使わずに何回も使われるとうっとうしい）
- ソリューション事業部（以下「ソ事」と略記する）
3. 箇条書きを使わない
結局、何を言いたいのかよく分からないパターン
箇条書きにすることで、各項目が独立し全体イメージが把握しやすくなる。
本日発生した障害について、原因の報告、ユーザへの影響、恒久対応、恒久対応までの暫定対策と体制について、
打ち合わせをお願いします。場所は3F A会議室で、時間は15:00からでお願いします
本日発生した障害について、以下打ち合わせをお願いします。
■ 報告内容
・原因
・ユーザへの影響
・恒久対応
・恒久対応までの暫定対策
・体制
■ 日時と場所
・3F A会議室
・06/16(月)15:00～16:00
4. 箇条書きでインデントを気にしない
何でもフラットパターン
箇条書きにしていても、インデントをちゃんとつけないと、階層が非常に分かりづらくて効果が無い。
本日発生した障害について、以下打ち合わせをお願いします。
■ 報告内容
・原因
・ユーザへの影響
・恒久対応
・恒久対応までの暫定対策
・体制
■ 日時と場所
・3F A会議室
・06/16(月)15:00～16:00
本日発生した障害について、以下打ち合わせをお願いします。
■ 報告内容
・原因
・ユーザへの影響
・恒久対応
・恒久対応までの暫定対策
・体制
■ 日時と場所
・3F A会議室
・06/16(月)15:00～16:00
5. 見てもらいたい箇所を強調していない
該当箇所を自分で探せパターン
文章が短ければそれでも良いが、ログのバックトレースなどをノーヒントで探せと言われると厳しい。
エラーになったジョブはエンドユーザではなく、テストジョブの為問題なし。
下記ログ参照
I, [2013-12-17T07:20:36.540877 #3824] INFO -- : message={"job_id":3593,"tasks":[{"params":{"file":"13872648367750000000876.doc","filename":"hoge.doc"},"type":"office2rpcs"}],
"user_id":"test_user","organization_id":"test_organization","app_id":"testprint"}
E, [2014-04-04T02:23:11.276469 #2665] ERROR -- : engine failed: file_access_error
E, [2014-04-04T02:23:11.276602 #2665] ERROR -- : /var/worker/current/lib/base.rb:108:in `raise_engine_error'
エラーになったジョブはエンドユーザではなく、テストジョブの為問題なし。
下記ログの赤字部分参照
I, [2013-12-17T07:20:36.540877 #3824] INFO -- : message={"job_id":3593,"tasks":[{"params":{"file":"13872648367750000000876.doc","filename":"hoge.doc"},"type":"office2rpcs"}],
"user_id":"test_user","organization_id":"test_organization","app_id":"testprint"}
E, [2014-04-04T02:23:11.276469 #2665] ERROR -- : engine failed: file_access_error
E, [2014-04-04T02:23:11.276602 #2665] ERROR -- : /var/worker/current/lib/base.rb:108:in `raise_engine_error'
6. 表を使わない
何でも箇条書き＋カンマで頑張るパターン
列が揃っていないので非常に見づらい。箇条書きでも、複数項目ある場合は表を使用すること。
悪い例
- test.tif : 200dpi、1ページ、カラー
- test2.tif : 200dpi、10ページ、カラー
- sample.tif : 400dpi、100ページ、モノクロ
- hoge.tif : 400dpi、100ページ、カラー
ましな例
| ファイル名 | 解像度(dpi) | ページ数 | カラー |
|---|---|---|---|
| test.tif | 200 | 1 | カラー |
| test2.tif | 200 | 10 | カラー |
| sample.tif | 400 | 100 | モノクロ |
| hoge.tif | 400 | 100 | カラー |
7. 表の左寄せ・右寄せが適当
左寄せ・右寄せなんて何でもいいじゃないパターン
同じ値でも整列が違うだけで見やすさが異なる。
以下のようにすると見やすい。
- 見出しは中央寄せ
- 文字は左寄せ
- 基本的に左から読むので、左寄せの方が見やすい
- 数値は右寄せ
- 右寄せにすると、桁が揃って分かりやすい
- 数値と文字が混在の場合、「$100,000」とか「15%」といった表記の場合は右寄せ
- 文字・数値でも全て同じ文字数なら中央寄せのほうが見やすい場合もある
悪い例
| ファイル名 | 解像度(dpi) | ページ数 | カラー |
|---|---|---|---|
| test.tif | 200 | 1 | カラー |
| test2.tif | 200 | 10 | カラー |
| sample.tif | 400 | 100 | モノクロ |
| hoge.tif | 400 | 100 | カラー |
ましな例
| ファイル名 | 解像度(dpi) | ページ数 | カラー |
|---|---|---|---|
| test.tif | 200 | 1 | カラー |
| test2.tif | 200 | 10 | カラー |
| sample.tif | 400 | 100 | モノクロ |
| hoge.tif | 400 | 100 | カラー |
8. 図を使わない
何でも文字で頑張るパターン
システム構成を知らない人にとっては、どこが問題かイメージが湧かない。
そういうときに図を使えば簡単に理解できる場合がある。
MQとロードバランサのコネクションが切れた時に、ADCがResetコマンドをWorkerに送信していなかった。
そのため、Workerがコネクション断を検知できずに、ハーフコネクション状態になり、ジョブ取得ができない状態になった
MQとロードバランサのコネクションが切れた時に、ADCがResetコマンドをWorkerに送信していなかった。
そのため、Workerがコネクション断を検知できずに、ハーフコネクション状態になり、ジョブ取得ができない状態になった。
構成と原因箇所は下記図参照。
9. 例を書かない
想像しろパターン
例えばエラー発生時にログを追加する対応を行った場合、レビュー時にログにどんな内容が出力されるかはコードだけ見てもさっぱりわからない。
なので、エラー時の原因追跡に必要な情報が足りているか判断できない。
begin
# httpリクエストを送信
res = execute(client, request)
return handleError(res )
rescue => e
# エラーが発生した場合、ログを出力する
logger.warn("Error occurred: " + e.getAllError()) #<==== 追加箇所
end
[WARN ] [2014-05-30 19:11:36.000587] Error occurred: {
"errMsg" : "externalstorage.cannot_execute",
"errCode" : 11020001,
"httpReq" : null,
"httpResp" : {
"statusCode" : 400,
"headers" : {
"Expires" : "Fri, 30 May 2014 10:11:36 GMT",
"Transfer-Encoding" : "chunked",
"Date" : "Fri, 30 May 2014 10:11:36 GMT",
"Keep-Alive" : "timeout=10",
"Content-Type" : "application/json; charset=utf-8"
}
出力例を出すことで、どんな内容が表示されるのか、出ている情報に過不足が無いかといった認識を合わせることができる。
10. 具体的じゃない
人によって解釈が分かれるリスクしかないパターン
悪い例
- 規定残業時間を越えない
- 規定時間って何時間？
- 100MBファイルのアップロードに数分かった
- 数分って何分？（１分？３分？５分？８分？１分なら速くない？）
- 「普通な用紙」 の条件でOCRのパフォーマンスを計測する
- 「普通」な用紙って？（A4？カッコの意味は？）
- クラウド開発部に提案する
- 開発部の誰に提案？（担当者の山田さん？、上司で部長の佐藤さん？）
- （テスト仕様書で）正常に終了すること
- 「正常」って何をもって正常と判断？
ましな例
- 残業時間が規定時間の20時間を越えないようにする
- 100MBファイルのアップロードに5分かかった
- テスト用紙(*)の条件でOCRのパフォーマンスを計測する(*400dpi, A4, モノクロ, 用紙の文字密度は5%)
- クラウド開発部の佐藤部長に提案する
- 正常に終了すること（ステータスコードが200であること)
11. 結論を最初に言わない
自分の苦労話を聞いてパターン
障害報告では、原因・影響・対策などの優先度が高い（＝知りたい）ので、そういったものから先に書くべき。
見る人は、調査者の苦労話を聞きたいのではなく、結論を知りたい。結論が分からない状態で読み進めるのは苦痛。また、後日見たときもまた、最初から読まなければならず、苦痛。
1. 概要
2. 調査詳細
3. 原因
4. 発生条件
5. 影響
6. 対策
1. 概要
2. 原因
3. 発生条件
4. 影響
5. 対策
6. 調査詳細
12. 結論をあいまいにする
とにかく逃げ道を用意するパターン
自信がないのか、責任を取りたくないのか、逃げ道を確保したいのか、
意味も無く「可能性」・「思われます」を多用して曖昧にする。
悪い例
- 期日までに終わらない可能性があります。
- 当該情報が漏洩しても、お客様やシステムに対しての影響はないと思われます。
- 基本的には本現象は発生しない。
13. 否定文を多用する
結局、どっちなの？パターン
否定文を使うと、以下のデメリットがあるので、肯定文を使用するようにする。
- 頭の中でその反対を考えないといけない
- 最後まで読まないと分からない。最後で逆転するので分かりにくい。
・無償での対応はできない。
・Officeファイルは対応していない。
・有償での対応となる。
・対応するファイルはPDFのみ。
二重否定は更に最悪。ぱっと見たとき、「？？？」となる。
# ログ出力しないリクエストヘッダ以外は、ログ出力する
if !notOutputHeader?(header)
logger.info(header)
end
# ログ対象のリクエストヘッダのみ、ログ出力する
if outputHeader?(header)
logger.info(header)
end
14. 計算しないといけない
結果は何となくわかるけど、具体的な数値は自分で計算しろパターン
クイズじゃないので、読者に無意味な計算はさせない。
悪い例
（例）パフォーマンス改善報告
変更後のほうがパフォーマンスが向上した
| 回数 | 変更前(秒) | 変更後(秒) |
|---|---|---|
| 1 | 15.4 | 13.2 |
| 2 | 19.2 | 16.5 |
| 3 | 13.4 | 11.2 |
| 4 | 16.9 | 16.2 |
| 5 | 12.6 | 11.8 |
ましな例
変更後のほうが12%パフォーマンスが向上した
| 回数 | 変更前(秒) | 変更後(秒) | 向上率 |
|---|---|---|---|
| 1 | 15.4 | 13.2 | 16% |
| 2 | 19.2 | 16.5 | 16% |
| 3 | 13.4 | 11.2 | 19% |
| 4 | 16.9 | 16.2 | 4% |
| 5 | 12.6 | 11.8 | 6% |
| 平均 | 15.5 | 13.7 | 12% |
15. 意味のない英語を使う
自分が知らない単語を覚えたり、周りがちょっと使っていると、意味も無く自己満足的に英語を使いたくなるパターン
しかも、英語のほうが日本語より長くなってかえって読みづらい、かつ相手が分からない可能性を高くするなど、
一体誰が得するのかもよく分からない。
相手を考えないで使う英語はただの自己満足なので、極力日本語を使用する。
このバジェットをオーソライズするためには、アウトプットごとにマイルストーンを設定し、
適切なリソースをアサインし、プロアクティブにハンドリングすることによって、
今回のスキームをカスタマーとコンセンサスを得ることが最もプライオリティが高いタスクです。
ましな例
バジェット → 予算
コンセンサス → 合意
16. 理由・経緯といった説明が無い
後で見ると何だっけ？パターン
結論・結果だけ記載して、そこに至った理由・経緯が無いと、
後日見たときに「何でその方法にしたんだっけ？」「別の方法はどんな問題があったんだっけ？」となる。
悪い例
-
外部からは直接DBにアクセスできないので、当該情報が漏洩しても、お客様やシステムに対しての影響はない。
- 何故外部からアクセスできないか理由が不明
-
今回はプロセスのフリーズ対応は実施しない
- 何で対応しないのか不明（工数的な問題か、技術的な問題かすら分からない）
17. 誤字・脱字
見直しくらいしろよパターン
誤字・脱字があまりに多いと、「見直ししたの？」「ほんとに調べたの？」とドキュメント全体の品質を無意味に疑われる。
１０分の見直しをケチったばかりに、レビュー時間が延びる・指摘事項の議事録書く量が多くなるといったことになり、見直しよりはるかに多くの時間がかかることになる。
書く改善策をリスと化し、チケットに追加し手億
↓
各改善策をリスト化し、チケットに追加しておく
18. 対象者を考えていない
ドキュメントを読む人が、上司なのか、メンバーなのか、新人なのか、アーキテクトなのか、営業なのか、技術職なのかなど、対象者のスキル・想定レベルによって、書く粒度・単語が変わってくる。
にも関わらず、そういったことを全く考えないで、自分の書きたい粒度で書くパターン
レビューで「これじゃ読む人が分からないよ」と指摘を受けたときの返答が以下のようなケースは典型的
-
自分以外は分かると思った
- 新人でありがちな、意味も無く自分を過小評価。その根拠は？
- XXXさん（チームで一番詳しい人）は分かると思った
- 言い換えると自分＋一番詳しい人以外の人は分からない文書
-
元の文書がそうなっていた
- もはやコピー元の作成者に責任を丸投げ
19. 何も考えず、既存のドキュメントを活用せず、新規に作成する
何でも自分で新規に作りたいパターン
テストケースや仕様書フォーマットなど、汎用的なものはこれまでの担当したプロジェクトや類似のプロジェクトから流用できるケースは多々ある。そういったことを考慮せずに、一から作る
その結果、ケース漏れが多かったり、フォーマットがバラバラになる系。
20. 何も考えず、既存のドキュメントをコピーする
19のケースと逆で、何でも何も考えずにコピーするパターン
既存のドキュメントを流用することで、品質確保・工数削減・フォーマット統一などのメリットは当然あるので、どんどん流用するべき。
しかし、コピー元のドキュメントが「正しい、品質が高い、完璧だ」と勝手に思い込み、分かりづらくないかを考えない。
その為、レビューで指摘すると「コピー元がそうなっていた」という、指摘者からすると「知ったことか」と言いたくなる言い訳にもならない返答をすることもしばしば。
流用するのは良いとして、流用元の不足している、分かりづらい箇所を精査し、自分で追加・修正することは必要。
最後に
- ドキュメントを見る人は内容を理解したいのであって、以下のような作業はしたくない。
- 文章の校正（見直し係？）
- 作成者の意図の読解（国語のテスト？）
- 結論を探す、無いので考える（クイズ？）
- 分かりにくいドキュメントの場合、レビューで大量の指摘・何回もレビューとなり、自分はおろか、他人の工数も大量に消費するので、分かりやすいドキュメント作りを実践しよう。
- 表記ゆれや、一文が長いなど、プログラムで機械的にチェックできるケースは、textlint等のツールを用いた方が良い。