この記事の概要
エンジニア的な文化・行動として「ドキュメントを残そう」をよく聞きますよね。
私の在籍するQiita株式会社では、社内の情報共有もかなり強く意識しています。
普段からドキュメントを残している中で、どんなものが効果的だったかを記事にしてみました。
なお、ここでいうドキュメントとはコード内のコメントやREADMEではなく社内Wikiのようなものを指しています。
残して良かったドキュメント
定期的に人に説明する内容
- 入社時にやること
- 今導入している技術やサービスのまとめ
- 制度上のフローやガイドラインなど
新しく入社した人に説明する内容や、チーム間で異動があったら共有すべき内容などのイメージ。
自分は「この内容、何度か人に説明してるなあ」と気付いたらドキュメント化するよう心がけています。
また、これらがしっかり残っていると、次の「新しく何かを始める際の記録」が取りやすくなります。
新しく何かを始める際の記録
- 技術を導入する際の選定の比較や議論
- 制度が変わる際、過去とこれからの差分
- 大きめなプロジェクトのまとめ
議論したことや決めたことを都度記録し、将来の自分たちが振り返れるドキュメントを作るイメージ。
現時点での情報はある程度まとまっている前提です。
これらのドキュメントを書く際に参考資料として「定期的に人に説明する内容」のリンクが貼ってあると非常に役立ちます。
あるドキュメントを入り口にして変更差分をどんどん辿っていけるため、色々な判断がしやすくなるでしょう。
フィードバックのまとめ
- Request for Comments
- 社内検証中に見つけた問題点
- ユーザーやクライアントの皆さまからのフィードバック
日々のフィードバックをトピックごとにまとめておくイメージ。
社内で今あるものに対して「これってどう？もっとこうなって欲しいとかある？」とコメントを求めるものから、利用者の皆さまからいただいた意見まで、色々な種類のものがあります。
「新しく何かを始める」にあたって、何から始めるかを決めるときにこれらの内容を見ながら決めることも多々あります。
調査記録
- 技術の調査
- 市場の調査
何を調べたのかと、いつの調査なのかがタイトルやタグで分かりやすいと重宝。
調べたときに使えなかったとしても、後から別なプロジェクトの参考資料として役立つ場合も多いです。
残してもいまいちだったドキュメント
いつからいつまでの話か分からない
- タイトルに「新」とか「最新」とかついているけど明らかに現在は実施していない
- 最終的に完了したのかしてないのか、読んでも分からない
- 過去に書かれてメンテナンスされていない「将来やりたいことリスト」
現在の状況にフィットしているのか、既に解決しているのか、どこまで進んでいるのか……。
一目で分からないドキュメントは残っていても解読に時間がかかります。
振り返りやまとめがない
上の「いつからいつまでの話か分からない記録」と似ているかもしれません。
今まさに進行中に見える内容では、後から読み返しても困惑してしまいます。
また、世に出した後の反応や修正点がないと、後から担当する人が大変です。
「リリース完了！おしまい！」では、ドキュメントが存在している意味とは？となってしまうでしょう。