はじめに
エンジニアリングマネージャーをしています、芦川です。
エンジニアのためのドキュメントライティング （ジャレッド・バーティ 著 /ザッカリー・サラ・コ―ライセン 著 /ジェン・ランボーン 著 /デービッド・ヌーニェス 著 /ハイディ・ウォーターハウス 著 /岩瀬 義昌 訳）をインナーソースの観点から読んだ記録をブログにしたいと思います。
結論
インナーソースの観点から見たドキュメントライティングの重要ポイントは以下のとおりです。
READMEの重要性
プロジェクトの最初に見るドキュメントとして、READMEは極めて重要です。
協働プロセス
ドキュメント編集はコードレビューと同様に協働的なプロセスであり、フィードバックを取り入れて改善していくことが大切です。
効率化
他者との協働は時間短縮につながり、強い人材のコントリビューションが効率を高めます。
建設的なフィードバック
個人を非難せず、コンテンツ改善を目的としたフィードバックが重要です。
感謝の姿勢
コントリビューションに対しては必ず感謝を示し、適切に検討して受け入れるかどうかを判断します。
完璧主義の回避
公開時に完璧なドキュメントは存在しないため、公開後のフィードバックと修正を重視します。
明確な責任者
最終承認者やコードオーナーを明確にし、管理責任を明確にします。
フィードバックの重視
ユーザーサーベイやフィードバックチャンネルを通じて、継続的な改善を図ります。
信頼関係の構築
フィードバックの反映状況を伝え、社内での小規模なDevRel関係を築きます。
適切な管理
ドキュメントオーナーを決め、放置されたリポジトリを防ぎます。必要に応じて廃止の判断も行います。
貢献への報酬
コントリビューションに対しては、適切な称賛と報酬を提供します。
インナーソースの観点の重要な記述の抜粋
CHAPTER1 読み手の理解
- README
- インナーソースに限らず、そもそもREADMEは誰もが最初にみるドキュメントで超重要。
CHAPTER4 ドキュメントの編集
- コードレビューと同じで、ドキュメント編集は協働的なプロセス。受け取ったフィードバックを取りいれて改善していく
- まさにこれはインナーソースと同義。「協働プロセス」という用語で広く調べていくと、インナーソースはもっと広がりを見せるだろう。
- 編集は他人とやれば時短になる
- 効率化という意味でも、自分でうんうん悩んですごく時間を使うよりは他人にまかせてフィードバックをもらったほうが時間短縮になる。単純にインナーソースにもそういうメリットがうまれる。そこに強い人がコントリビュートするほうが時間短縮になる。
- フィードバックは、批難するものではなく、コンテンツの改善を目的としたものである
- これは、コントリビュートするときの重要なマインド設定。管理するトラステッドコミッターやチームに対して不平不満を言う場ではない。
- 必ずフィードバックをうけて改善しなければいけない、ではない。必ずするのは、感謝のみ
- 必ずコントリビュートされたらすることは感謝のみ。レビュー、マージはちゃんと検討して受け入れるかどうかを判断しよう。
CHAPTER7 コンテンツの公開
- 安心せよ、リリース時に完璧なドキュメントはない、公開してからフィードバックをうけて修正していけばよい
- インナーソース化する際のマインド設定に当てはまる。不完全とわかっててよいのだよ。
- 最終承認者は明確にしよう、有害なドキュメントをリリースしてはいけない
- 受け入れる際の制約はちゃんとつけよう。コードオーナー、トラステッドコミッターを明確にしよう。
CHAPTER8 フィードバックの収集と組み込み
- フィードバックチャンネルの作成を作ってユーザーサーベイをしよう
- ここもインナーソースに関連する。リポジトリ管理者が利用者やコントリビュートしてくれる方にアンケート取ろう。
- ユーザーのフィードバックが伝わっていることをユーザーに届ける、信頼関係を構築する
- コントリビュートやフィードバックを信頼関係を作ろう。つまり、社内での小さいDevRel関係と言える。
CHAPTER11 ドキュメントの保守と非推奨化
- ドキュメントオーナーを決める、NGな状態は「ドキュメントの責任は全員にある = 誰も責任を負っていない状態」
- まさに管理者不在のゾンビリポジトリ。こうなってはいけない。捨てる判断も含め、コードオーナーを決めよう。
- ドキュメントの保守に報いる
- コントリビュートしてくれたら、称賛と報酬は当然だ。
マインドマップ
終わりに
インナーソースという観点から読むことで、普段見落としがちなドキュメントの奥深さを再認識できました。今回ご紹介したポイントが、皆さんの日々の業務やチーム運営に少しでも役立てば嬉しいです。
この学びを活かし、チームのドキュメント文化をさらに良いものにできるよう、これからも探求を続けていきたいと思います。
