[ Docs ] チームのための正しい文書化方法

チーム内の文書管理の必要性

文書化を大事にする理由はあります。

1. 担当者に長く質問しないことで、お互いの時間を節約できます。
2. 最初から文書だけで問題を解決するのは大事です。
3. 口で伝える方法で情報の汚染が発生するのを防ぐことができます。

このよに文書化が不十分な場合、上記のようなイシューが発生する可能性があります。

 

文書化を始めましょ！

文書化を進めるために必要な要素を並んでみました。

悩むほど良い文書化ができると信じます。

1. チームメンバーと一緒にポリシーを設定したか
   - Fileの名前はどうするか
   - Directoryの仕組みはどのように分けるのか
2. 文書を作成、更新したユーザーの記録を追跡が可能か
   - 変更したユーザーが誰なのか時間とIDがでる
3. 作成、更新、廃棄の時レビューをするのか
   - 誰に確認をもらえばいいのか
   - どの程度の規模の更新からレビューをするべきか
4. 管理するツールは下記のような機能があるのか
   - Gitのように以前と現在の違いが見られるのか
   - 作成が簡単なのか
   - 読みやすいのか
   - 拡張性がよいか

 

読者が誰なのか考えること

新入社員のonBordingのための文書か経歴者の設計整理のための文書か、色んな理由で文書の難易度が決められます。

読者のレベルを低めにするほど、より多くの人が読めることもありです。

1. Experence
   新人なのか経歴者なのか
2. Domain
   同じ分野で働く人かどうか
3. Goal
   簡単にみるべきか細かく見るべきか

 

文書の種類を分けよう！

文書は種類によって区分した方がいいです。

見方や手順を教えてくれてユーザーを徘徊させずに探索できるようにしてください。

1. 参考用文書資料
2. 設計文書
3. チュートリアル
4. 概念の説明
5. レンディングページ

 

文書作成とレビューの際に考える点

1. 正確性
   内容が正しいのか
2. 明確性
   話したい部分が明確なのか
3. 完全性
   説明の流れが良いのか

 

文書化のアンチパターン

1. しなくても仕事はできるので面倒くさい追加作業だと考えられるかも
2. 作る人が頑張ってもその恩をもらう人は他人だから
3. 会社の財政状態や日程に余裕がないとできなくなります

 

結果

文書化は、チームワークと知識共有、問題解決、品質向上を支援し、組織が持続的に成長し発展するための重要な活動だと思います。

Reference - Software Engineering at Google
https://www.oreilly.co.jp/books/9784873119656/

Googleのソフトウェアエンジニアリング