3年間のエンジニア業務で習得したドキュメントライティング

みなさんこんにちは。沖縄でWEBエンジニアをしているishikiです。
本記事では、前職で3年間システムエンジニアをしていた経験をもとに、ドキュメントライティングで気を付けていることを記述していこうと思います。
どなたかのお役に立てると嬉しいです。
※ご指摘・フィードバック歓迎

0.本記事の対象者

• ドキュメント作成が苦手なITエンジニア

1.目的に紐づく情報を記載する

エンジニアがよく作成するドキュメントとして要件定義書、基本設計書、詳細設計書、テスト仕様書、利用マニュアルなどがあると思います。
例えば利用マニュアルの場合、入れるべき情報は下記です。

• システムを利用するための操作方法

• 操作の注意点はあるか

  • 例）マルチブラウザでログインできない etc…

この利用マニュアルにシステムの内部処理（詳細設計書レベルの情報）が記載されていたらどうでしょうか？

• ボタンをクリックするとXXX関数でYYYの分岐が走る

混乱しますよね。
利用マニュアルを読むのはシステムを使うユーザです。
ユーザ視点で見るとシステムを動かしたいだけなので、内部の処理を記載されると混乱してしまいます。

なので、ドキュメント作成に着手する前に記載すべき情報を洗い出すと良いでしょう。

2.読み手の知識レベルに合わせる

書き手と読み手で知識に差がある場合は、読み手が理解しやすい表現にする必要があります。

知識に差があるケース
- 顧客とエンジニア
- 新人とベテラン

理解が難しいであろう言葉・表現については、

• わかりそうな言葉に置き換える。

• 補足説明を入れる。

のような対応をしていきます。

「理解が難しい箇所がどこかわからない」場合は読み手からフィードバックをもらい、修正や補足をしていくと良いでしょう。

3.メンテナンス性を考慮する

ドキュメント作成の一番の課題は、作成したドキュメントがメンテナンスされずに負債になってしまうことでしょう。
例として詳細設計書を挙げると、設計内容と実装が異なる場合があります。
実装は正しく書かないとシステムが動かないですし、テストを通過できません。
しかし、詳細設計書については実装の変更点を反映しなくても、システムが動きます。また内部向け資料になるためレビューが甘くなります。（顧客へ提出する場合でも、詳細設計書と実装の対応がとれているかまでは確認しないでしょう）
このような経緯から、詳細設計書がメンテナンスされず、誤った情報を持ち続けるケースが多々存在します。メンテナンス不備が原因で、プロジェクト新規メンバーが誤った仕様理解をしてしまいバグに繋がる、ということが懸念されます。
では、ドキュメントをメンテナンスし続けるにはどうすれば良いのかでしょうか。

DRY原則に従う

重要なのはDRY原則に従い「記載内容の重複を排除する」ことです。

例）詳細設計書
詳細設計書のマスタ情報は実装（ソースコード）となります。
なので、実装を見ればわかることは記載しません。
小規模システムであれば詳細設計書そのものを排除するのも有りですが、
大規模システムで実装のみを見てシステム内部の処理を把握する運用を行うと属人化に繋がってしまいます。
なので「システム内部処理の全体像を把握するための資料」という位置付けで詳細設計書を作成するのが良いと思います。
例えば、アクティビティ図に記載するのと同じレベルの粒度までであれば、メンテナンス性も損なわれず、システム内部処理を把握できると思います。
既存システムだと詳細設計書がすでにあると思うので、
1.既存ドキュメントの記述粒度や形式に合わせるか、
2.メンテナンス性の高いドキュメントを新規作成するか、
はチーム内で相談が必要かと思います。

例）ファイル定義書
システムでファイルの入力・出力処理がある場合、ファイルフォーマットを決定する必要があります。それらはファイル定義書に記載します。
さらに基本設計書などでA画面のXボタンをクリックするとファイル定義書No1のファイルが出力される、という記載をすることがあります。
この場合は「〜を参照」とだけ記載し、ファイル定義書と基本設計書の情報重複を排除することをおすすめします。

バージョン管理

言うまでもないですが、ソースコードと同様にドキュメントもバージョン管理しましょう。誤操作をしても復元するすることができます。
バージョン管理の容易さの観点から、Gitで差分が可視化できないExcelやPowerPointを避けてください。
大体のドキュメントは テキストファイル（.txt）、Markdown、draw.io で事足ります。

追加でツールを導入すればOffice製品も差分を表示できるようですが、手間がかかります。
参考：https://qiita.com/RyoWakabayashi/items/bde84624bffc1f68071d
顧客提出が必要等の理由でOffice製品を扱う場合は、Gitコメントで変更管理する必要がありそうです。

また、Office製品は装飾の自由度が高いがゆえに、体裁を整えるために時間が溶けていきます。よって作業時間短縮の観点からおすすめしません。

4.ビジネス用途の文章を書く

基本的なビジネス文書の書き方なので、詳細は省略します。

• 長文ではなく、箇条書きで書く

• 主語・述語・目的語を明確に書く

• 抽象的な表現を避け、具体的に書く

• ドキュメント間で言葉・表現を揃える

• 話し言葉を使わない

5.体裁を整える

見た目の綺麗さ以前に情報の粒度をそろえることが大切です。
粒度がそろっていれば、Office製品を使わずとも テキストファイル（.txt）で理解しやすいドキュメントを作成できます。

• 情報の階層構造を明確化する

• 同じ階層の情報粒度をそろえる

その他細かい点は、本や記事が多く出ているため省略します。

おわりに

ドキュメント作成が苦手なエンジニアは多いと思います。
しかし、良いドキュメントを作成できると報告・連絡・相談のタイミングで認識齟齬を防ぐことができます。具体的には、同じ内容を何度も説明したり、作業の手戻りが発生するのを防ぐことができます。
コミュニケーションコストが下がれば、本質的なタスクに集中できるというメリットもあります。
また、ソースコードを書くときと同じように、DRY原則や単一責務の原則など意識するとドキュメント作成が楽しくなるかもしれません。

以上、お役に立てば幸いです。
ご覧いただきありがとうございました。