ドキュメントを変更の一部として扱う
動作が変わる場合、ドキュメントを更新するのに最適なタイミングは同じプルリクエスト内です。レビュアーは実装と説明をまとめて比較でき、バージョンタグはドキュメントをリリースされたコードと一致させます。
- 説明対象のコンポーネントの近くに、焦点を絞ったREADMEを置く。
- 公開動作、設定、運用手順が変わったときはドキュメントの更新を必須にする。
- 継続的インテグレーションでリンクとスタイルのチェックを行う。
- リスクの高いランブックやリファレンスページには明確な所有者を割り当てる。
書く前にドキュメントの種類を選ぶ
チュートリアルは一連の流れを通して教えます。ハウツーガイドはタスクを解決します。リファレンス資料は正確な動作を説明します。解説は背景とトレードオフを提供します。4つすべてを1つの長いREADMEに混ぜると、それぞれを使いづらくなります。
アーキテクチャ決定記録も有用なパターンです。検討理由が新しいうちに、背景、決定、代替案、結果を記録します。Markdownは別の公開ワークフローを必要とせず、記録をコードの近くに置くことができます。
コード例をテスト可能で正直なものにする
読者は例をコピーします。必要なimport、現実的な名前、期待される出力、関連するエラーパスを含めましょう。スニペットが意図的に不完全な場合は、その旨を明記します。テスト済みの小さな例は、もっともらしく見えるだけの大きなブロックよりも価値があります。
```bash # Validate docs before opening a pull request npm run lint npm run typecheck ``` Expected result: both commands exit with status 0.
レビューしやすい差分を重視する
リポジトリが一貫して1行1文の規則を採用している場合のみその方式を使い、それ以外は自然に折り返してツールに表示を任せます。事実関係の編集の際にファイル全体を再フォーマットするのは避けます。安定した見出しと参照スタイルのリンクを使えば、大きなドキュメントもノイズの少ない差分で変更しやすくなります。
- 生成されるアンカーでも有用な、具体的な見出し名を付ける。
- テーブルは狭く保ち、文章の多いセルを避ける。
- リポジトリと一緒に移動するファイルには相対リンクを使う。
- 例にシークレット、プライベートログ、マスクされていない本番データを貼り付けない。
変換を移行の出発点として活用する
Wordファイル、スプレッドシート、PDF、スライドには、docs-as-codeワークフローにまだ適合していない貴重な知識が含まれていることがあります。Markdownに変換すればプレゼンテーション層の多くが取り除かれますが、開発者はそれでも見出しの正規化、リンクの修正、ファイルの分割単位の決定、技術的な正確性の確認を行う必要があります。
変換後のバージョンがレビューされるまで、ソースドキュメントを保持します。計算されたデータや署名付きの記録の場合、読みやすいMarkdownスナップショットがリポジトリに追加された後も、オリジナルが真実のソースであり続ける可能性があります。