ドキュメント、書けてますか?

Transcript

1. ドキュメント、書けてますか? 渡邊裕貴 / 2021-06-30
2. ドキュメントとは 当たり前すぎてかえって正確な定義を言いにくい気がするが ここでは 「業務に役立つ情報を記載した文書や図」 としておく
3. とある人の意見 プログラマーがドキュメントを書かない理由 (和訳が怪しいところがあるので原文を読んだ方が良い ) • 書くことは難しいから • ドキュメントは納品すべき成果物ではないから • 書くための良いツールがないから
4. 書くことは難しい • 業務に役立つ情報を書くことは難しい • コーディングよりも難しい なぜなら • 情報を整理し言語化するやり方は自明ではない • 自然言語の文章に問題があってもエラーは出ない
5. 難しさを正しく認識する 綺麗なコードを書けないとき • ❌ コメントやドキュメントで理解を助ける • ⭕ コメントやドキュメントを読むともっと分からなくなる • 綺麗なコードを書けない人は綺麗なドキュメントも書けない
6. 難しさを正しく認識する 2 • ❌ 書く時間がないから書けない • ⭕ 書くスキルがないから書けない • 人は、自分ができることだけをやろうとしがち ◦ スキルがないと、所要時間の見積もりもできないので敬遠する • 書くスキルを持つ人は、自ら書く時間を作ろうとする
7. メンテナンスは書くことよりも難しい ドキュメントのメンテナンスはコードのメンテナンスよりも難しい コードと同様に、ドキュメントも • 設計をよく考えろ • 継続的にリファクタリングしろ
8. 難易度に応じて担当者を決める 多数の文書や図からなる全体の構成を整理する 一つの文書の中身の構成を整理する 要件と仕様と設計の関連が理解できる説明を書く 比較的複雑な機能の動作の解説を書く 細かい機能の動作の解説を書く 既に書かれた文章の誤りを訂正する 難 易 全員ができる必要はないが 誰もできないのは困る
9. やっていこう • 自分ができることをやろう • 自分ができることを増やそう ◦ 練習しよう • 良いドキュメントとはどのようなドキュメントか? ◦ 考えよう ◦ みんなで話し合おう 書けない 書かない