序章
- エンジニアは、品質の高いドキュメンテーションの欠如に不満を抱く.
- Googleは、ドキュメントをコードのように扱うことで、保守を楽にしている.
何がドキュメンテーションとして適格か
- 「ドキュメント」には、コードに対するコメントも含んでいる.
何故ドキュメンテーションが必要か
- ドキュメントはの恩恵は下流の工程で得られる.
- ドキュメントが教えてくれること.
- ドキュメントの恩恵は即時的なものではなし.
- 文章を書くことは、ソフトウェアエンジニアのスキルの1つである.
- 苦手意識を持っているエンジニアも多いが、読み手の観点から物事をみることが重要
- ワークフローやツールの制限は、ドキュメントを書くことを難しくさせる.
- ドキュメントが既存コードの保守を楽にしてくれるものではないと思っている人がいる.
- エンジニアリングチームにテクニカルライターは必要ではなし.
- 全エンジニア自身がテクニカルライターを目指すということではない.
- ドキュメントを書く労力を減らす方法を考えるべきである.
- ドキュメントの利益
- APIの意味
- APIの説明や定義が出来ない場合は、設計が不十分である.
- 履歴としての役割
- コード上で凝ったことをすべきではないが、良質なコメントが意味の理解を助けてくれることはある.
- アクセス数の増加
- ドキュメントがしっかりしているAPIは、設計が優れているAPIであると推測される.
- うわべだけのように聞かれるが、製品の保守にどれだけ力を入れているのかがわかる.
- GoogleのC++スタイリングガイドによると、**「読者に向けて最適化せよ」**と箴言されている.
ドキュメンテーションはコードのようなものである
- ドキュメントを書くことはコードを書くことと相違なし
- ドキュメントにはルール、特定の構文、スタイルがある.
- コード同様にドキュメントにもオーナーがいるべきである.
- オーナーが別々の場合は、カノニカルなドキュメントを指定すること（似ているドキュメントから代表的なドキュメントを選ぶこと）が重要である.
- ドキュメントのルール
- 内部的なポリシーかルールを持つべき.
- ソースコントロールシステムの管理下に置かれるべき.
- ドキュメントを保守する責任を持つオーナーシップ制度がある.
- 変更についてレビューをする.
- コード内でバグが追跡可能にする.
- 定期的に評価されるべきである.
- 正確性や鮮度面で計測可能にする.
- Googleのwiki時代
- 問題点が顕在化していた時代
- オーナーがいないので、ドキュメントが廃れていった.
- 上手い具合に階層化出来なかった.
- ドキュメントを修正できる人と利用する人が別であった.
- 利用するユーザは、間違いを確定することが困難
- 誤りを報告する簡単な方法がなし
- ドキュメントの品質が年次の不満、第1位になる時もあった.
- ソースコントロールシステムで管理することで劇的に変化した.
- バグの特定に役立つ
- ドキュメントのレビューが可能
- Markdownにしたことで、簡単に理解可能
- コード内にドキュメントを埋め込むことにした
対象読者を認識せよ
- 序文
- エンジニアがやりがちなことは、ドキュメントを自分のために記載する.
- 自分のために書くのは無益というわけではない
- 時が進むに連れ、前提条件が成り立たなくなることがある.
- ドキュメントを書き始める前に、誰に対してのドキュメントかを明確にすべき
- デザインドキュメント
- チュートリアル
- APIドキュメント
- 専門家、初心者両方に、完全かつ正確なリファレンス情報を提供する必要がある.
- ドキュメントは完璧である必要はなし
- 最近自分が身に付けたドメイン知識が欠けている人に書くことを覚えておけばよい.
- 対象読者の類型
- 対象読者による分け方
- 詳細な説明を省くことは、初心者には嬉しくないが、熟練者には嬉しいこと.
- トレードオフの関係がある
- 重要なのは、ドキュメントを短く、明確に伝えること.
- 対象読者がドキュメントに出会う際のタイプ別
- 捜索者
- 一貫性が重要
- 常に似ている形式になるように記載すべき
- 遭遇者
- 曖昧な考えしか持っていないので、明確性が重要
- **TL;DR宣言文はよく使われる.
- 利用者と提供者でも分けるべき
ドキュメンテーションの類型
リファレンスドキュメンテーション
- エンジニアが書かなければならない、コード上に書くコメント
- 「APIコメント」と「実装コメント」に分かれる.
- APIコメントは、ユーザが作者と同様の知識がないことを前提に書かれるもの
- 実装コメントは、ドメイン知識をもっているもの
- Java、Pythonの場合は、Javadoc、PyDoc、GoDocがある.
- C++の場合は、ヘッダーファイルに記載する.
ファイルコメント
- 読んでいるコード内に何が記載されているか.
- 1段落目、2段落目で簡潔に説明出来ていないAPIは、あまりよいAPIとはいえない.
// SECRET
クラスコメント
- 現代的なプログラミング言語は、オブジェクト指向プログラミングである.
- 例: Fooクラスはx、y、zを含み、Barを行えるようにし、Bazという特徴がある.
// SECRET
関数コメント
- Googleでは、全ての自由関数及び、クラスの公開メソッドにはその関数が何を行うのかを記載する必要がある.
- 明示的な定型分の節を追加すると、コメントが冗長にはなるが、明確にはならない.
- Google Docstringを完全に否定している気もする.
// SECRET
デザインドック
- 主要PJT着手前に記載する.
- 設計
- セキュアリティ上の影響
- 国際化
- ストレージ要件
- プライバシー など
- デザインドキュメントをレビューしておくと、有益となることが多い.
チュートリアル
- 新しいチームにジョインする人のためのドキュメント
- チュートリアルを書く最良の機会は、チームに初めて参加する人が参加したときである.
- **チュートリアルには、全てを記載する**
- 特定の構成、許可状態、ドメイン知識は一歳前提してはならない.
ダメなチュートリアル例
ダメなチュートリアルを改善したもの
概念的ドキュメンテーション
- リファレンスドキュメンテーションを強化する役割
- 概念ドキュメントは記載するのが最も難しいドキュメントである.
- 専門家と初心者両方に向けたものである.
ランディングページ
- 一般的には、チームページがある.
- 目的を明確にすべきである.
- チーム向けと利用者向けのドキュメントが混在している状況などは良くない.
ドキュメンテーションのレビュー
- レビューの種類
- 正確性のための技術的レビュー
- 明確性のための対象読者レビュー
- 一貫性のための作文法レビュー
- Google wikiについて
- GoogleのC++スタイルガイドは良い状態に保たれていた.
ドキュメンテーション哲学
- 誰が、何を、いつ、どこで、何故
- 始まり、中盤、終わり
- 優れたドキュメンテーションの特徴的要素
- 完全性、正確性、明確性
- 完全にしようとすると、明確性が失われるので、トレードオフの関係
- そのドキュメントにとって、役目をこなしているドキュメントである.
- APIドキュメントに、設計上の決定事項などを記載することは良くなし.
- ドキュメントを廃止する
- 古いドキュメントは問題を引き起こすことがある.
- 3ヶ月間手を加えられていないドキュメントは、emailを通じて、知らせる必要がある.
- ドキュメントの最終更新日時、管理者、最終レビュアーなどを記載するのがよい.
テクニカルライターが必要なのはどんなときか
- 重要なPJTには、テクニカルライターが必要なのではないだろうか.というのは間違った仮説
- テクニカルライターは、文法や構成、見栄えなどを優れたものにしてくれるが、逆インセンティブが発生する.
- 重要なPJTでは、テクニカルライターに任せて、自分はドキュメントは書かないということ.
© 2024 nakadats. Created by Satoru Nakadate.