Melting Pot of Thoughts

SaaSスタートアップのCTOです。思考の整理のため考えたことをメモ書きレベルでアウトプットしていくブログです。

ドキュメントのアーキテクト

開発組織においてドキュメントは重要です。
開発組織のドキュメントには要件定義書・設計書等の開発資料や、運用作業の手順書、実装ガイドライン、開発体制の説明など、様々な種類のものがあります。

ドキュメントにより用途は異なりますが、以下のようなメリットが得られる点は共通しています。

  • 暗黙知形式知に昇華
    ドキュメントとして思考ロジック・作業手順を明文化することで、個人だけが知っている・理解している情報(暗黙知)をチームに還元し、チーム全体が理解できる形での情報(形式知)に昇華できます
  • 認識齟齬の削減
    文章化されることで口頭での情報共有よりも精度高く認識が共有できます
  • 属人性の排除
    特に運用手順書など、ドキュメント化しておくことで業務の属人性が排除でき、変化に強い組織になります
  • 品質向上
    ドキュメント化することで作業工程や思考背景が可視化されるため、問題がある点に自身で気づきやすくなり品質が向上します。またドキュメントがあることで他の人からレビューを受けることができるようにもなり、それによっても品質向上に繋がります。

特にフルリモートの組織においては、ドキュメントが果たす役割は非常に大きいため、ドキュメントを整備することを強くオススメします。フルリモートはオフィス勤務に比べ、暗黙知が多くなり、認識の齟齬も増え、業務の属人性が高くなりがちなので、まさにドキュメントはピッタリな改善策だと思います。

 

しかしドキュメントは読まれなくなることも多いです。

「どこにドキュメントがあるのか探しにくい」「文章が読みにくい」「内容が古くて信頼できない」などなど…。

せっかくドキュメントを作ってチームの資産にしていっているのに、それが活かされていない(もっというと負債になっているものがある)のはもったいない話です。

 

もしこういった課題意識があるのでしたら、ドキュメントのアーキテクト役を作るといいと思います。

とはいえそんなに大げさなことをする必要はないです。

 

最初にやるべきことは今あるドキュメント群を整理していくことです。
フォルダ階層をわかりやすくし、フォルダ名もパッと見て伝わるようにし、古いドキュメントを削除しましょう。削除するのが怖ければ、アーカイブフォルダを作り、そこに移動するとかでもいいでしょう。
ドキュメントの名前も必要に応じて、わかりやすい名前に変えるといいでしょう。

そういったことをするだけでも、大幅にドキュメントが見つけやすくなり、また新しくドキュメントを作る際にどこの階層にどんな内容で作ればいいのか迷うことがなくなります。

 

次にやるべきことは、ドキュメントが綺麗に整理された状況が続くよう、チームをサポートすることです。
システムアーキテクト同様ドキュメントアーキテクトは、骨組みを作って終わりではなく、それがきちんと現場にフィットしているのか見守りサポートするまでが仕事です。
まずはどういう考えでドキュメントを整理していて、今後どういうルールで作っていきたいのかチームに共有するといいでしょう。
新しくドキュメントを作る人がいた際にはどこの階層にどういう内容でドキュメントを作ると良いかサポートしたり、あるいは新しく作成されたドキュメントを見て配置場所や名前を少し直したりとか。フォーマットが決まっているドキュメントだと、テンプレートを用意しておくのもありだと思います。
チームの方針にもよると思いますが、ドキュメントは気軽に書けるようにしたほうがどんどんドキュメント化が進んで良いので、ルールは極力なくしたほうがいいでしょう。
フォルダ階層・フォルダ名が適切で論理構造がわかりやすくなっていれば、ルールが無くても自然と、ある程度適切な配置でドキュメントが作成されていきます。

 

ドキュメントアーキテクトは「チームの古株で」「情報整理や生産性向上に対する熱意があり」「論理的な情報構造化が上手な」人が向いているでしょう。
エンジニアリングマネージャーがいるのであれば、職責的にはその人がやるのはピッタリですが、熱意あるエンジニアが手を挙げてやるのでもいいと思います。

「情報を論理的にきれいな構造に整理し」「チームの開発者がスムーズに働ける体験を設計する」という意味でシステムのアーキテクチャ設計に通じる部分があるので、その経験はドキュメントアーキテクト役をやったエンジニアにとって今後システム設計をする上で活きる経験になります。