はじめに
こんにちは。名古屋スタジオでサーバーエンジニアをしている川島です。
今回は開発や運用時に必要なドキュメントを継続して書いていく際の考え方などを紹介したいと思います。
なぜドキュメントを書くのか
業務に必要な資料がある状態が当たり前のように考えがちなのですが、実際のプロジェクトやチームの状態によっては資料がなく人づてでのみ知ることができたり、資料はあっても情報があまり充実していないことなどがあります。
この状態で考えられるデメリットとしては次のようなものがあります。
- ノウハウ共有が進みにくい
- 業務の移譲・引き継ぎのコストが大きい
- 問題が起こった時、対処できる人間が仮にいなかった場合に詰みやすい
- 異動が進行した組織において、情報を持っている人間が不在になってしまう
このような状態はチームやプロジェクトにとって健全ではありません。
では、ドキュメントが存在している状態であればどうなるか考えてみましょう。
- （Best） ドキュメントを読むだけで誰でも作業内容が理解でき、周囲のサポートを受けながら作業ができる状態
- （Better） ドキュメントを読むことで、自身で作業を行うきっかけができる状態
ドキュメントを読めば誰でも作業できるようになれば業務の効率は非常に最適化されているともいえます。
理想ではありますが、完成度が高いものを常に維持し続けるのはかなり労力がかかります。
ドキュメントを読むことで、作成者に作業内容を確認したり、実際の作業者がより充実したものになるようメンテナンスしていくきっかけができることが重要と考えています。
これらの作業を継続して行なっていくことによって、長期的に見るとチーム、プロジェクトの業務が少しずつ健全になることが期待できます。
※前提として、普段業務にあたる人は作業手順をドキュメントに残していくようにしていくことが大事になります。
書き方のtips
いきなり完璧なものを書こうと思うと気後れしてしまう人もいるかと思います。
最初は箇条書きレベルでも良いので気軽に文章化してみましょう。
最低限の情報でも文書として共有されていることが大切です。
ちょっとした内容でも気軽にドキュメントを作っていく作業を継続できることが理想です。
少しずつ内容を充実させながら、どんどんドキュメントを書いていきましょう。
メンテナンスについて
ドキュメントは、業務の変化に合わせてメンテナンスをしていく必要があります。
しかし、すべての資料を完全な状態に維持し続けるのは現実的に難しい場合もありますし、何よりドキュメントを書こうとする意欲が削がれてしまいます。
これを避けるためのポイントは以下の3点です。
- 不変なもの、そうでないものを分ける
- 変わっていくものだけメンテナンスしていく
- チームで協力する
1,2について例に挙げるとこのようになります。
- 変わらないもの → ある機能の開発をすることになった経緯や、当時の設計意図など
- 変わるもの → 仕様書
- APIの仕様変更で、パラメータの名前が変わったり、レスポンスとして返す値を変更する場合などが考えられます。
メンテナンスの対象となるドキュメントがいくつかある中で、業務に合わせて優先度を設定してメンテナンスしていけるとより効率よくドキュメントを健全な状態で維持できると思います。
3については、ドキュメントに関わる全員がアップデートすることで、ドキュメントの鮮度が維持しやすい状態ができると思います。
実際に利用され続けるドキュメントを書くことができる体制を作っていきましょう。
ドキュメントを残す場所
社内ではesaやGithub Wikiを利用しています。
プロジェクトによって定められているものを利用しましょう。
esaはWIPとして保存できる機能とプレビューを見ながら編集できる機能が非常に使いやすいためよく利用しています。
まとめ
今回はドキュメント作成と、作ったドキュメントをメンテナンスしていく際の考え方についてご紹介しました。
ベテランは自分の知見を積極的に共有することでチームの助けになりますし、普段あまりドキュメントを書かない人や経験が浅い人の気づきなども新しい発見や業務につながる可能性もありますので、まずは軽くメモを残すような気持ちでドキュメントを書いてみてはいかがでしょうか。
ドキュメント作成の活性化の一助となり、チームやプロジェクトの健全化に貢献できれば幸いです。
最後までお読みいただきありがとうございました。