😎

ドキュメントを書くときに気をつけること

2023/12/10に公開

ドキュメントを書いた後に、チーム内にレビューを出すんですけど、以下の点で指摘を受けることがありました

API仕様がチーム内で正しく理解されていないこと(前提が違っている)

これがなぜ起きるか？というと、API仕様書にユースケースといった書かれるべき情報が不足していて、
チーム内で統一したフォーマットとなっていないため発生していたので、見直したことがきっかけになります。
※ただ、これはAPI仕様書に限らず、どういった資料においても共通して言えることだったので記載しております

ドキュメントの目的を定義する

「何のために・誰のために・何を書くのか、を明確に定めること」が、読みやすいドキュメントを作成する上で重要
そこでまずは「何のために、何を伝えるドキュメントなのか」を定義します
いきなり書き始めるのではなく、ほんの数十秒でもいいので考えてみてください

目的を一言で定義できるのが理想
定めた目的をドキュメントの「概要」として書く
一つのドキュメントに対して目的は一つに絞ります。目的が複数あるドキュメントは読み手に高い負荷をかけてしまいます
（これって結局、何について書かれたドキュメントなんだろう？と余計な思考をさせてしまうことが理由としてあります）

主目的が複数存在する場合はドキュメントを分けるべき、だと考えています。
主目的に関連する副目的ならOK
（×）このドキュメントは、案件の概要と仕様をまとめつつ、進行の方法について書くことが目的だ
（○）このドキュメントは、機能の仕様を、後からジョインしてくる人も理解できるように整理するのが目的だ

書く時に筋道が立っているかを強く意識する

読み手が知っている/理解しやすいことから順を追って説明する
読み手は、階段を一段ずつ上がっていくように説明してもらえると理解しやすいです
反対に、知らないことが一段目にあるとつまづいて理解が難しくなる
これは、書き手は、読み手がどこまで知識があるのか？が不明なので、前提の説明が必要になるためです

読み手が階段の一段目を登れるかに配慮する
この「読み手が知っている/理解しやすいことから順を追って」というのが重要であり、筋道を立てる際に必要です

私は下記の順番を採用しています

全体から部分への展開
概要から詳細への展開
既知から未知への展開
まず重要を説明
まず相手が知りたいことを説明
作業や手順を流れに沿って説明

表や図を用いる

表や図を適宜用いることで、ドキュメントの効率性と快適性を飛躍的に高めることができます。
「色々と工夫しているのに結局伝わっていない…」と思った時は、表や図を用いることで解決に向かうことが多いです。

私は以下のように使い分けています。
一覧（リスト）・比較・時系列で、物事の流れを示したいとき　→　表を用いる

見た目に関わる表現をするとき　→　図解を用いる

同じ粒度の項目　→　リストを用いる

データや処理の流れを伝えるとき　→　UMLを用いる

書いた後の推敲

一般的な人間の能力は、書く力より読む力の方が優れていると言われています。
推敲する際は、以下をチェックリストとして気にしてみてください。

タイトルから文章の目的が分かる
全体の構成がロジカルに組み立てられている
見出しから内容が分かる
文と文とのつながりがある
必要な情報の抜け漏れがない
不要な情報が書かれていない
1文が長すぎない
表記の揺れがない
固有名詞の誤りがない
誤字脱字がない

終わりに

以上になります。

どういうドキュメントが読みやすいのか、それはなぜなのか、ポイントを絞って書かせていただきました。
参考になれば幸いです。