ドキュメントの育て方

チームで知見を貯め、会社を会社として成立させる方法

前口上

小説家なんかだと割合個人プレーの場合もあるのですが、何かを制作するためには複数のスキルが必要なことも多く、個人単体で全てをカバーできないので、規模の大きいビジネスは徒党を組むことが多いです。

ソフトウェア開発も例外ではなく、一定規模のアプリやWebサービスは複数人で作るのが通例で、規模が大きくなると認識の違いによって不具合だったり、本来同じレベルの人でも開発速度に差が出たりするものです。

社内Wikiへのノウハウのストックを推奨するのは属人化を避けミスを防ぐ優れた方法ですが、ツールを導入したもののストック化が進まないという会社もしばしば見ます。そういったケースでの一つの参考として個人的ドキュメントの育て方をまとめておきます。

持続的活動には持続的投資をする

情報のやりとりにはフローとストックがあり、前者がチャットツールで後者が社内wikiなどです。ストックの中でも議事録や障害報告、作業ログなどワンタイムなものとAPIやテーブル定義の仕様など長期的にメンテが必要なものがあります。

社内にノウハウを貯めるという観点だと長期的に使えるものほど価値が高いわけですが、同時に長期的にメンテをする努力が必要ではあります。

社内にwikiツールを導入するのは始まりでしかありません。ツールを導入した際に書いてと号令をかけるだけだと多くの場合進みません。

持続的な活動には持続的な投資が必要で1on1なり朝会なりでノウハウを貯める必要性を何度も説き、wiki化できることはないか何度も聞くことが大切です。

ディレクトリの構成を決める

一番最初にはじめる時は階層関係をある程度決めることも大切で、ページをどこに作ればいいのかの指針があると進みやすいです。一方で最初から深すぎると速すぎる最適化というかオーバーエンジニアリングになるので細かすぎない方が良いです。

一例を置いておきます

仕様/
  Backend/
    テーブル定義
  Frontend/
  iOS/
  Android/
  共通/
    API仕様
how-to/
  Backend/
    本番サーバーへの繋ぎ方
検討/
  Backend/
    認証ライブラリーの比較
障害/
  2021/
  2022/
    本番DB破壊の件
ログ/
  KPT/
    2022-04-01
  議事録/
    2021/
    2022/
      アプリをFlutterにするか
個人/
  yamada/
  suzuki/
    手元環境が何もしていないのに壊れた作業ログ

まず書くことに慣れていくことを目指す

また最終系は上記の構成に均等にストックされていくことが目標なのですが、最初から100%を目指さない方が良いです。自分も含めこういったツールを導入する人は根がブロガーというかQiitaなどの技術系サイトに息を吸うように記事を書ける人な場合もありますが、長文を書き慣れていない人もしばしばいます(特に非技術職)

自分が携わるサービスは多くの場合WebサービスでRDBMSを使っていることが多いので、テーブル定義から始めることが多いです。次にAPIの仕様でしょうか。OpenAPI化なども魅力的なオプションですが全くの更地の場所まずは情報を集めることから始めるとよいかと。

入れて欲しい共有ディレクトリでなく個人ディレクトリに似たような作業ログや調査メモが量産されることもあるのですが、最初のうちはそれを咎めない方が良いです。まずドキュメントを書くことに慣れてもらう。

ページの移動なんて後からできますし質の高い個人メモは共有財産に少しずつ変えていけば良いと思います。