今年の半分ぐらいが過ぎた頃からDOOR賃貸を開発・運用をしております @iwtn です。
これまで社内では3つのWebのサービスに関わってきました。
それぞれがWeb業界では歴史のあるサービスで、すべて8年以上サービス開始から経過しております。
途中から開発に参加してきた開発者は、システムの全体像を掴むのに苦労するものです。
大抵の場合、まず最初に読むのはプロダクトの概要をまとめたドキュメントやREADMEです。
そしてサービスを運用していく中で、日々ドキュメントを作成し、更新しています。
そんな経験の中から、ドキュメントをどう日々書いていくべきか、というところをまとめました。
3行で
- ドキュメントはマニュアルとログに区別される
- マニュアルは常に更新を怠らず、可能な限り自動化して少なくする
- ログはその時の情報をしっかり残すことで後で活用できるので、潤沢に取っておく
マニュアルとログの区別
マニュアルは、繰り返し参照され正しいものが常にひとつになるように更新が必要なものです。
ログは、議事録や障害時のポストモーテムなど一時的に発生し、その後更新しない情報の記録です。
更新する必要の有無で判別
マニュアルを更新しないと、実行する際に誤りが発生します。リカバリできるものなら良いのですが、致命的なミスにも繋がります。
ログを更新すると過去の情報を改竄してしまうことになり、正確な記録になりません。記録は正確でないと、その先に誤った判断をしてしまう元になります。
なにかドキュメントを作成するとき、更新し続けて行く必要があるかどうかで、マニュアルかログかを判別できます。
そのドキュメントは作成すべきなのか
マニュアルは常に更新に必要があり、管理コストが高くなるため、最低限に抑えましょう。
開発環境の設定などはDockerなどのコンテナやAinsbleなどの構成管理ツールを使って自動化するのがベストです。
逆に、ログは情報を残しておくために、必要な分だけ潤沢に残しましょう。デジタルデータはあっさり消えてしまうときは本当に消えてしまうので、そのときにしかわからないことはまるっとアーカイブしておくと後で調査できます。
また、あなたの頭の中だけにあることも記録には残りません。文章として残しておくと、引き継ぐ人が助かるかもしれません。
ストレージのコストはすごく下がっておりますので、容量的な問題はあまりないと思います。あとで調査するときのためにまとめておくことも大事ですが、時間がないときはどんどん記録しておく方針で良いと思います。
マニュアル
環境の立ち上げ方だったり、テストの実行方法だったり、主にリポジトリごとのREADMEとして作られます。
その他、自動化するには頻度が少なすぎる運用手順などは、社内wikiなどにマニュアルを作成しておきましょう。メモ程度でもドキュメント化されていることで、微妙な手順の変更なども修正していくことで致命的なミスを防げます。
繰り返しになりますがマニュアルはソースコードと一緒で常に更新が必要です。マニュアルに影響する箇所のコードを修正した場合は、同じ修正にマニュアルの更新も含めておくと良いでしょう。レビューも一緒にしてもらうと実装との乖離が防げます。
README
GitHubでライブラリを公開している方はよくご存知だとは思いますが、社内のプロダクトであってもREADMEは書くべきです。
そのリポジトリの目的、使用方法、単体で動作するサービスであれば起動やバージョンアップの方法などを載せておきます。
最も良いのは、そのREADMEを読みさえすれば、少なくともそのリポジトリの開発まで持っていける状態であることです。
ですので、ミドルウェアなどのセットアップなどを別リポジトリで管理している場合は、そちらへのリンクを貼っておくとより親切です。
手動運用のための手順書
手順書は、誰でもできるように厳密に記述しておきましょう。また、その目的も簡単に併記しておきましょう。実はその手順の実行が不要になっている場合などに気づけます。
内容は、事前チェック→実行→結果の確認の流れで作成しておきましょう。
手順書通りに実行できなかった、もしくは結果が意図するものと違った場合は、そのログを残し、実行できるようマニュアルの更新もしておくと良いです。
また、実行時のログを毎回残しておくと、いつそれを行ったかの記録にもなります。
ログ
ログは、開発者以外のステークホルダーとの会議の議事録や、なんからの技術選定をしたときの意思決定の様子、トラブル発生時のポストモーテムとして作成します。
会議の議事録
議事録は、決定したいことや決定事項を完結に毎回まとめ、関係者が誰でも見れる場所に置いておくことで、参加者も最低限に減らせます。
技術選定の経過と結果
技術選定の記録は、どうしてこのような決定をしたのかを残しておくと、途中から参加した開発者がその意図や目的を知れます。システムのリプレースなどでその意図がわからないと、本当にそれを変更してよいか調査が必要になります。できる限りなぜそれを選んだのかを残してください。
開発言語、フレームワーク、データベース、検索エンジンなどのミドルウェアの選定も作りたいシステムの全体像が明らかになっている上で比較検討されていると、説得力のある資料になります。また、次に技術選定する際の参考にもなります。
個人的に使いたかったから、という理由であればそれでも大丈夫です。そういった場合は然るべき技術が他にあれば、そちらに変更するという決定がしやすいので、それはそれで助かります。
ポストモーテム
意図せぬトラブルや障害から、そのプロダクトについて学ぶことは多いので、ポストモーテムとして記録しておきましょう。過去にあった障害を記録しておくことで、新しい障害が起こったときの調査に役立つ場合もあります。
以下は、オライリーから出版されているTeamGeekの1章24ページからの引用で、このような内容が記録されていれば、後々役に立つと思います。
優れたポストモーテムには以下のことが含まれる。
● 概要
● イベントのタイムライン(調査開始から解決に至るまで)
● イベントの根本原因
● 影響と損害の評価
● すぐに問題を解決するための行動一式
● 再発を防止するための行動一式
● 学習した教訓
感想
長く続くサービスのプロダクトであればあるほど、開発者は入れ替わります。開発者は入れ替わってもドキュメントはその場に残せます。良いドキュメントがあると、運用の負荷も減り、楽しい開発を続けられます。ぜひ、良いドキュメントを残して、良いサービスを継続的に提供できる開発を行っていきましょう！