ドキュメンテーションは機能である
ドキュメンテーションは製品とは別物ではありません。製品の一部なのです。
多くの開発者が、以下のような欠陥のあるパターンに従っています：
- 機能を作る。
- 機能をテストする。
- 機能をリリースする。
- 機能をドキュメント化する。
ユーザーはコードを体験するわけではありません。彼らが体験するのは、インターフェース、ワークフロー、そしてドキュメンテーションです。ユーザーにとって、ドキュメンテーションは一つの「機能」なのです。
作成者は、すでに製品を理解しているため、ドキュメンテーションを疎かにしがちです。なぜその決定を下したのか、自分なら分かっています。APIがどう動くのかも、ショートカットも知っています。
ユーザーはそうではありません。あなたにとって当たり前のことが、彼らにとっては不可解なことなのです。
同じ質問が繰り返されるなら、それを「ドキュメンテーションの負債」として扱いましょう。もし同じ質問が2回繰り返されたなら、問題があります。製品が分かりにくいか、ドキュメントが不完全かのどちらかです。時にはAPIを修正する必要もありますが、多くの場合、ドキュメントを修正する必要があります。
優れたドキュメンテーションは摩擦を減らします。そして、以下の問いに素早く答えてくれます：
- これは何か？
- なぜ使うべきか？
- どうやって始めるのか？
- 最善のアプローチは何か？
- シンプルな例は何か？
目標は網羅性ではありません。目標は勢い（モメンタム）を生み出すことです。
優れたドキュメンテーションは、パターンと意図を教えます。なぜそのフレームワークが特定の仕組みで動いているのかを説明します。これにより、ユーザーの生産性が向上します。
ドキュメンテーションは、目立たない形でビジネスに影響を与えます：
- 採用率
- オンボーディングの速度
- サポートコスト
- コミュニティの成長
- 開発者体験
優れたドキュメントの影響は、すぐには分かりにくいものです。しかし、不十分なドキュメントの欠如には、即座に気づくことになります。
ドキュメンテーションは、あなた自身のためでもあることを忘れないでください。それは、未来の自分に向けて知識を保存するものです。決定事項を記録しておくことで、数ヶ月後に答えを再発見する手間を省けます。
製品の品質とドキュメンテーションの品質は連動しています。
- 分かりにくいソフトウェアには、より多くのドキュメントが必要です。
- 分かりやすいソフトウェアには、それほど必要ありません。
- 優れたドキュメンテーションは、悪い設計を浮き彫りにします。
ドキュメンテーションを後付けの作業として扱うのはやめましょう。明確さを強制するための手段として活用してください。明確さは設計を向上させ、向上した設計は製品を向上させます。
出典: https://dev.to/stinklewinks/documentation-is-a-feature-228n