ドキュメンテーションむずかし

SE である以上、ドキュメンテーションスキルの習得は避けて通れない。

カジュアルな例ならば、はてなブログや Qiita への記事投稿が挙げられる。 このほか、クライアントへの説明資料であったり、仕様書や API リファレンスの作成であったりといった局面では、ドキュメンテーションスキルの差が如実に表れる。

一方で、僕はこのドキュメンテーションスキルに対して並々ならぬ苦手意識を抱いている。新人研修の時分、議事録や週報の添削で屈辱的な評価を受け、甚だショックを受けたものである。

しかし、僕もそろそろ「文章書けません」が許されなくなりつつあるので、いい加減、ドキュメンテーションへの苦手意識を克服せねばならない。

そこで、まずは改善への第一歩として、「よいドキュメント」と「自分の書いたドキュメント」の間にどこまで深い溝があるかを認識する必要がある。

そのために、まずは自分自身で「よい文章」を定義づけてみた。

よい文章のパターン

  • 読み手を意識している
    • 読み手を不安にさせたまま先に進まない
      • 本題に入る前に導入がある
      • 全体の流れが、読み手の意識に沿っている
  • ドキュメントの目的が明確である
  • テーマと結論が対応している
    • 結局何が言いたいのか分かる
  • 文章が一意解釈できる
    • 主語・述語が整合している
    • 5W1Hで書かれている
  • 一文が簡潔である
  • 事実と推測と主張が分かたれている
  • 一つの節内で、時間の流れは常に一定方向

アンチパターン

  • わかりやすくするためにウソを書いてはいけない
    • 相手にはウソの情報が伝わる
  • 不確定な情報を、常識や思い込みで補完してはいけない
  • 原因の異なる問題を一つの文に混在させてはいけない
  • 読み手を置き去りにしてはいけない
    • 未定義の用語を使用してはいけない
    • 論理の流れを断ち切らない・論理を飛躍させない

まだまだありそう。

それに、こういう項目を挙げたところで所詮は単なるチェックリストに過ぎない。

ただし、上記のパターンはいずれも合格基準が曖昧であり、結局、心がけだけではドキュメント品質は向上しない。

具体的な実践手順までレベルダウンが必要そうだし、必要に応じて機械によるアシストも必要かも知れない。