新規プロジェクトのドキュメント運用手引

こんにちは。
SO Technologies で新規プロダクト開発のテックリードとして働いている島田です。

この記事の背景

エンジニアとして働き始めていくらか経ちましたが、これまでのどのアプリケーション開発プロジェクトでもほぼ例外なく、ドキュメント運用に関して何かしらの問題がありました。
ドキュメントに残しておくべき情報が一部書かれていなかったり、過去に作られたものがアップデートされないままになったりといったことが少なからず起こっており、「このドキュメントに必要なことが書いてあります」と手放しで言えるような状況は稀でした。

ドキュメント運用が上手くされていないと、新しいメンバーのオンボーディングに手間取ったり、必要な情報を得るために多くの時間を費やす必要が出てしまいます。
そういった点に関して、個人的に以前から問題意識を感じており、上手く計画的に運用出来ないものかと思いながら日々の開発を行っていました。

幸運なことにこの会社では開発の責任者として、立ち上げ段階からプロジェクトに関わることが出来ました。そこでドキュメント運用に関して必要充分な、かつ書き手にとって負担がなるべくかからないようなルールを最初期から設け、この一年ほど実際に運用することにしました。

結果として、一年間ドキュメントは適切に書き足され、情報が古くならないよう保守され続けられていたように思います。
途中新しくメンバーが入った時も、その時点で必要な情報はほぼ全てドキュメントに残っておいたためにオンボーディングがスムーズに進められ、プロダクト要件が目まぐるしく変わる中でも、常に新しい情報にアップデートし続けられ、必要な時に必要な情報にすぐアクセスすることが出来ていました。

この記事では、自分たちのチームでどのようにドキュメントを運用してきたのかをまとめ、なるべく別の環境でも上手くいった点を再現出来るように紹介したいと思います。
これからプロジェクトを立ち上げる方はもちろん、現状のドキュメント運用に問題を抱えてる方にも参考にして頂ければ幸いです。

前提条件

内容に入る前に、どのような条件下でドキュメント運用がされたのかを紹介します。

チーム構成

チーム構成は以下の通りです。

• エンジニア: 3人
• プロジェクトマネージャー: 1~2人
• デザイナー: 0~1人

全体で4~6人チームにおり、エンジニアでありテックリードの自分1人だけが通しで参加し、他のメンバーは途中で抜けたり入ったりしています。

プロジェクトの変遷

プロジェクトは、広告代理店にいる、Web広告運用者の業務を支援するアプリケーションを作るというものでした。
以下の通り結構な頻度でチームメンバーが入れ替わっていたのですが、紹介されるドキュメント運用方法はその中でもちゃんと機能し続けていましたので、この方法の有効性を考える上での参考にして頂ければと思います。

まず、最初期はテックリードを務める自分とプロジェクトマネージャーの2人で、要件定義とアプリケーション設計を行っていました。

その後もう2人エンジニアと、1人のデザイナーを迎えて開発がスタートしました。

それ以降アプリケーションのリリースに向けて開発が進み、途中元々居たプロジェクトマネージャーが退任し、その業務を引き継いだ2人が新しくメンバーに加わりました。
この時が最も大所帯で、6人のチームで開発が進められていました。

開発を進めていたある時、諸事情あってアプリケーションの要件が大幅に変わることになりました。そこで元々実装されていた機能のほとんどを引き継ぎ、さらにいくつかの実装を加えた製品に作り変える事が決まります。
それに従って一度チームは解散し、テックリードの自分以外のメンバーは全員、一旦他のチームに移動することになりました。

その後新しく入ったプロジェクトマネージャーとテックリードの自分の2人で、再び要件定義と設計をしました。

現在は、その後迎えた2人のエンジニアを加えた4人で開発を進めています。

ドキュメント運用手順

ドキュメント運用は以下の手順に従って実行されました。

1: 運用リーダーを決める

経験上、ただ何も考えずにプロジェクトを始めてしまうと、ドキュメントは整備されないまま開発は進んでしまうものだと考えています。
従ってドキュメントを上手く運用するには、それを実行する意思を持ったリーダーと、その人が権限を行使出来る環境を整える必要がある、というのが根底のアイデアとしてあります。

なのでまず、ルールそのものを決める前に、誰がドキュメント運用を主だって行うリーダーなのかを決めるよう強く推奨します。

運用リーダーは、誰よりも真摯に運用ルールに従い、ルール通りに運用がされてない時にはメンバーをサポートしなければいけません。
そういった、人に先立って行動してリーダーシップを発揮できる人を登用することにまずは力を入れるよう勧めたいです。

リーダーシップを発揮できるのに加え、役割上ドキュメントを綺麗に保つモチベーションがある人はより運用リーダーに向いていると言えます。
例えばテックリードは、可能な限りプロジェクト全体の進捗や実装に関する最新の情報を知っていなければならないので、その人にとってはドキュメントが整備されてるかどうかが仕事の生産性に直結します。なので、多くの場合そのような立場の人に運用リーダーを任せると上手くいくのではないかと思います。
また同様に、プロジェクトの開発進捗に責任を持つプロジェクトマネージャーも運用リーダーに向いているのではないかと考えています。

2: ルールの制定をする

リーダーが決まったら、その人を中心にルールを決定します。
なるべく早いうちに、可能であればプロジェクトの最初期に決め、それを忍耐強く守っていくことをおすすめします。
後からルールが足されたり変更されたりすると、それ以前に書かれたドキュメントをそのままにしておくか、多くの労力をかけて修正作業を行わなければならないからです。

プロダクトの要件やチームメンバーの数によってどのようなルールが最適なのかは変わってきますが、ルールを守られやすくするために、なるべく数自体は少なく済むように努めるのを推奨します。

参考までに、私が所属しているチームの運用ルールをほぼ原文そのままで引用しておきます。

ルール①: 今後新しくメンバーが入って来たとして、その人が見る必要のある情報は全てドキュメントに残す

Slack や他の場所にも情報を残す事は出来るが、検索性に問題があったり、そもそも複数の箇所に情報が散らばっているという状況が好ましくないため、指定のドキュメントツールに全て残すようにすること。

新しく入ったメンバーも読むので、会議や 1on1 で彼らにコンテクストを共有せずとも、ドキュメントだけ読めば理解できるようになっていなければならないので注意すること。

ルール②: 決まったことのみ書く

メモ代わりに使う等、後々必要にならない可能性のあるものは残さないこと。

意思決定に必要となる議論がされている Slack のスレッドの URL 等を一時的に書いておくのは構わないが、必要なくなったら消すという事をする責任があることは忘れないようにすること。

ルール③: ルートになるドキュメントから辿れるように、新しくドキュメントを作る際は必ずそのURLを他のドキュメントに記述する

ルートとなるドキュメントはこちら: (著者注釈: 指定されたドキュメントのURLが入ります)

上記のドキュメントを樹状図のトップとして、新しく作られたドキュメントがその図のどこに位置するのかを、そのドキュメントの一階層上になるドキュメントにURLを記述して引用することで明示すること。

こうすることで、ルートとなるドキュメントから、リンク先にジャンプしていくことで全てのドキュメントにいつかはたどり着けるようになるので、時間さえかければ、検索機能を使ったり他のメンバーに質問をせずとも、新しく入ったメンバーは必要な情報を漏れなく参照出来るようになるためにこのルールを設けている。

ルール④: タグは全員と合意が取れるまで増やさない

(著者注釈: ドキュメント作成に使っているツールに自由に追加出来るタグを各記事に付与するする機能がついていて、それについて記載をしています)

タグが増えると、ドキュメントの検索や内容理解がしづらくなる。よってもし下記に含まれないタグを使用したい場合は、本当に必要かどうか考慮してメンバーに合意を取った上で追加し、下記の項を更新すること。

現状使われているタグ一覧 (最終更新: 2021/08/23)

• README : 職種に限らずメンバー誰もが目を通しておくべき資料であることを示す
• 開発関連 : なにかしら技術や開発に関連する事柄であることを示す
• ビジネス関連 : なにかしら、エンジニアのタスクに関わらない、ビジネス面に関連する事柄であることを示す
• 暫定資料 : 例外的にルール②が適用されない資料であることを示す (著者注釈: 議論中の内容にまつわる PlantUML で生成された図を残しておくために作りました。使っているドキュメントツール以外のプラットフォーム、例えば Slack 等では PlantUML に対応していないので、それを利用しているものは暫定資料としてそのドキュメントツールに残しても良いこととしました。)

3: リーダーを中心にルールを守りながらドキュメント運用していく

1 で決めたリーダーを中心に、ドキュメント運用ルールを実施します。
説明としてはこれだけなのですが、参考までに自分が一年間テックリードとして、上記で書いたような運用リーダーの役割を努めた中での所感を以下に書いておきます。

まず、リーダーの活動は特に最初の1~2ヶ月が手間がかかり、かつ影響が大きかったように思います。
最初期はドキュメントがあまり揃っておらず参考に出来るものが少ないため、ルールを逸脱したドキュメントがどうしても多く出てしまいます。
リーダーを決めている以上、良く言えば決定権が集中していて、悪く言えばリーダー以外が頑張る理由が希薄になってしまっているので、メンバー全員がルールに慣れるまでリーダーとしてたくさん行動を起こさなければいけませんでした。

自ら率先してドキュメントをルール通りに書き、誰かがドキュメントを追加したら必ず目を通すようにして運用上の間違いを指摘したり、時には自ら修正して「このように書くようにして下さい」と示すことも、幾度となく実施しました。
また、そもそも必要なだけドキュメントが書かれているかを常にチェックし、記述がされていないものに関してドキュメント作成を依頼するといったことも行っています。

幸いメンバー全員がドキュメント整備の重要性に理解があり、かつ人数も最大で6人ほどだったので、ある程度ドキュメントが揃って例が示せるようになる頃にはルールの遵守がメンバー全員に根付いていました。
また、数ヶ月前に新しく入ったメンバーも、ほぼ既存のドキュメントを見せてオンボーディング作業を個人で行っただけで、ルールと運用方法を理解してくれました。もちろん本人の学習能力の高さもありますが、それがしやすいように、そもそも質問をせずともルールを共有出来るようになったという点においては、成果があったと言えるのではないかと思います。

状況によっては、ここに書いたことをするだけでは必ずしも充分ルールを浸透させることは出来ないならないかもしれませんが、頑張りどころとその期間の目安として参考にしていただければと幸いです。

さいごに

4~6人規模の開発チームの立ち上げ期から、どうやってドキュメントを運用してきたのかをまとめました。

繰り返しになりますが、メンバーの人数や個性、作るものの種類によって運用の最適解は変わるので、都度ルールを考える上での参考にして頂ければ幸いに思います。