自分なりのドキュメント作成の心得とテクニック

備忘録として、自分なりのドキュメント作成の心得とテクニックを書き留めておきます。

ドキュメント作成の心得

• ドキュメントの目的は「読み手と書き手の情報の非対称性を解消すること」
• ドキュメントも製品の一部と考えること。決してオマケではない。
• ドキュメントには鮮度がある。製品のアップデートに併せてドキュメントも更新すること。
• 「ドキュメントを読めば、すべてを理解してもらえる」と考えないこと。
  • 「ドキュメントを読んでも、よく分からなかった」は、ドキュメントを改良するチャンスと捉えること。
• ドキュメントへの批判は必ず建設的提案を添えること。
  • ✗：「XXが分かりづらいです。」
  • ◯：「XXの表現では、YYケースのリスクが懸念されます。ZZと記載してはいかがでしょうか？」
• コンプライアンスを遵守したドキュメントであること。
  • いわゆる裏マニュアルのようなドキュメントは決して作成しないこと。
  • ドキュメントに組織の政治的事情・圧力を含めないこと。
• （個人的に）他人に向けて書くよりも、半年後・1年後の自分に向けて書くとモチベーションを維持できる。
  • 「半年後の自分は何も覚えていないだろうから、特にこの点は手厚く書いておこう」の心持ちでドキュメントを書くと、救われる時がある。

ドキュメント作成の下準備

• 読み手が誰か・読み手の知識量がどれくらいかを把握すること。
  • 読み手 = はじめて製品に触れる人なら、ドキュメントは教科書や入門書のように、一から十をカバーする形式が望ましい。
  • 読み手 = 同僚のエンジニアなら、ドキュメントは用語集や逆引き辞典やQ&Aのような形式で事足りるかもしれない。
  • 読み手 = エンドユーザーなら…、読み手 = カスタマーサポートなら…、と読み手とその知識量を考慮すること。
• 書き手と読み手の共通言語（ユビキタス言語）の用語集を作成すること。特に以下の観点を意識する。
  • 文脈により意味が変わる言葉
    • （個人的に）例えば「ドメイン」って言葉の扱い方にかなり苦労しています。共通言語の用語集作成に銀の弾丸はないと思うので、都度アップデートしていくしかないと思っています。
  • 書き手と読み手で解釈違いが発生しそうな言葉
  • 所属する組織やチーム間で解釈違いが発生しそうな言葉
  • 暗黙知。そもそも用語集に載せようと意識すらされない言葉
• ドキュメント生成ツールがあれば、採用を検討すること。
  • ドキュメント生成ツール自体の保守も勘案しないといけないので、採用は慎重に行うこと。
  • markdown などのシンプルなテキストファイルで事足りるなら、ドキュメント生成ツールは不要です。
• ドキュメントのレビュー期間を設けること。
  • レビュー時はドキュメント編集直後ではなく、一晩ほど時間をおくこと。
  • 可能なら、ドキュメントのレビューは編集者とは別の人が担当すること。
    • 最近ならAIにチェックしてもらったり、加筆してもらうと良いのかも？
• サンプルコードを記載するときは、テストも行うこと。

ドキュメント作成のテクニック

• 正となるドキュメントがただ1つ存在し、一元管理されていること。
  • 部署Xと部署Yで、それぞれのドキュメントがあり、それぞれ内容が矛盾している…といったケースは避けること。
• ドキュメントは常に最新の状態で保たれていること。
• ドキュメントに機密情報（ID、パスワードなど）は含めないこと。
  • もしドキュメントに機密情報を含める場合はパスワード制限やアクセス制限などをかけて、適切な管理下におくこと。
• ドキュメントの章の順序立ては論理的であること。
• ドキュメントに目次を設けること。
• ドキュメントに検索機能を設けること。
  • 基本的にエディタの検索機能で十分です。目視で探すのは手間と間違えやすさから避けたいです。
• 編集中の項目は、編集中であることが明示されていること。
• ドキュメントの更新履歴と更新日時も残すこと。
  • 更新履歴と更新日時も、ドキュメントの大切な要素です。
  • 更新履歴は、更新前と更新後の差異をまとめた文章であること。変更前が特に忘れやすいです。
    • ✗：「XXをZZに更新しました。」
    • ◯：「XXをYYからZZに更新しました。」
• 読んでドッキリ・ビックリする表現には、補足事項を手厚く記載すること。
  • 例1：コンテキスト（文脈）を裏切る表現。「しかし」や「ただし」から続く文章を指す。
  • 例2：読み手に強い制約を課す場合。「絶対にXXをしてはいけません。」や「XXの情報を忘れずに覚えておいてください。」などの文章を指す。
  • 例3：後述するクリティカルな情報の説明。
  • 「はじめに」のような項目を追加して、事前にドッキリ・ビックリを和らげること。
• クリティカルな情報の説明には、補足事項を手厚く記載すること。
  • 例：本番環境における操作手順の説明。
  • クリティカルな情報の説明文とその補足事項は、エクスクラメーションマークを付与したり、赤字や太字で強調すること。
    • 強調表現は乱発はしないこと。何でもかんでも強調してしまうと、どれが重要な情報か見失ってしまう。
• 文章は簡潔であること。
  • 二重否定（〜ではないわけではない）は、原則使わないこと。
  • 受け身・推測（〜と思われる）は、原則使わないこと。
• 文章は平易であること。
  • 文章の難易度は新聞記事に合わせると良いです。新聞記事 ≒ 中学卒業程度の文章力。
  • 原則として、難読漢字は利用しないこと。
• 1文 = 1意図とする。1つの文章に複数の意図を含めないこと。
  • 「そして」や「そのうえ」や「したがって」などの接続詞を含んだ文章は、その接続詞を起点に文章の分割を検討すること。
• 事実と書き手の主張は、明確に区別すること。
• 意図のない文章はドキュメントに含めないこと。
• 表記は統一すること。下記に例を挙げます。
  • 全角と半角
  • 大文字と小文字
  • アルファベット表記とカタカナ英語表記
  • 漢字を開くか
  • 日付のフォーマット
  • 数値のフォーマット
    • 単位は統一すること
    • 算用数字か漢数字か
    • カンマ区切りありか…など。
    • 複雑な数式は Latex を検討すると良いかも。
  • 同じ意味の言葉の表記を統一すること。
    • 「申し込み」と「申込み」と「申込」
    • 「押下する」と「クリックする」…など。
• 主語と述語は必ず明記すること。
• 誤字・脱字がないこと。
• 原則として、略称は利用しないこと。
  • 略称を利用する場合は「以降、〇〇とする」などの補足や注釈を追加すること。
• 原則として、指示語は利用しないこと。
  • 文章の冗長化を避ける場合は、指示語を利用しても良い。
• 文章は断定的表現であること。極力、曖昧さを排除すること。
• 過度な修飾語を文章に含めないこと。
• スラングは利用しないこと。
• 攻撃的な表現は利用しないこと。
  • 例：「こんな操作ミスをする人はいないと思いますが、」のようなテキストは不要です。
• 程度・量・頻度など定量的な情報は、具体的に明示すること。
  • ✗：「ある程度時間をおいて、XXをしてください。」
  • ◯：「5分ほど時間をおいて、XXをしてください。」
• チェックリストの文末は、「〜であること」や「〜が正である」にすること。
  • 文末が「〜であるか」の場合、Yes が正なのか No が正なのかで一瞬考えてしまう事があるので。
  • ✗：「XX の操作後、YY の状態は ZZ であるか」
  • ◯：「XX の操作後、YY の状態は ZZ であること」もしくは「XX の操作後、YY の状態は ZZ が正である」
• チェックリストは優先度レベルを明記すること。
  • 例：必須、推奨（非推奨）、任意の3レベル…など。
• 可能なら、図解を添えること。「百聞は一見にしかず」の通りで、図解があると理解が進みます。
  • 図解は簡潔であること。
  • 図解は最新であること。
  • 図解は正しいこと。
• 可能なら、サンプルコードを追記すること。
  • サンプルコードは簡潔であること。
  • サンプルコードは最新であること。
  • サンプルコードは正しいこと。
  • サンプルコードは実行可能であること。
  • サンプルコードは安全であること。
    • サンプルコードを実行すると本番環境に影響が出てしまう…などの重大な副作用が発生しないこと。
  • サンプルコードはカスタマイズ可能であること。
    • サンプルコードを元にカスタマイズして、実装しても問題なく動作すること。
• ドキュメント外の参考資料へのリンクURLは最新版であること。
• ドキュメント外の参考資料へのリンクURLがアクセス切れになっていないこと。