esa.ioをベースとした社内ドキュメント基盤の整備活動

2月から開始された、ゴールデンウィーク期間のキャンプ場予約争奪戦に裏技？を駆使して無事勝利し、ほっと胸をなでおろしている、MMM代表の国本です。

さて、MMMでは2017年から様々な施策を順次進めており、その活動の一つに『社内ドキュメント基盤の整備』というものがあります。

2015年の社内のドキュメント基盤としてQiita:Teamとesa.ioをしばらく並行運用した結果でご紹介の通り、MMMでは社内ドキュメントは現状esa.ioで一元管理していますが、運用開始から1年半が経過し、様々な課題が浮き彫りになってきました。

そこで、より使いやすく、より業務に活用できるドキュメント基盤を作り上げることをゴールに、全社員で協力して整備活動を開始しましたので、少しご紹介したいと思います。

浮き彫りになってきた課題

ドキュメントを探し出すことが困難

MMMでは『暗黙知を形式知にする』という前提のもとに、プロジェクト内のローカルルール、各種設計方式、技術情報、戦略や学習方法など、あらゆるジャンルを積極的にドキュメント化した結果、膨大な数のドキュメントがesa内に作成され、今欲しいドキュメントを直ぐに探し出すことが難しい状況に陥りました。

陳腐化されたドキュメント

明確なドキュメントの更新ルールを設けていなかったため、技術情報や、開発フローなど日々更新・改善されていく状況にドキュメントが追いついておらず、内容が陳腐化されているものが多数発生しました。

重複しているドキュメント

ドキュメント数が膨れるにつれ、上述のとおりドキュメントを探し出す手間が増え、結果的に内容がほぼ重複しているようなドキュメントが多数作成されるような状況に。

ディレクトリルールのカオス化

導入時点で細かいディレクトリルールを切ったものの、逆にドキュメントを設置する場所の判断に悩む結果となってしまい、各々がそれぞれの考え・想いでディレクトリに配備した結果、ディレクトリルールが形骸化してしまう状況に。

中途入社やインターン生にやさしくない

入社直後に読んで欲しい社内規則や、プロジェクトルールなどがドキュメントにまとまっているものの、ディレクトリが分断されているため、探し出すことが困難となっていました。

ドキュメントの整備をどうすすめるか

これらの課題解決に向けて、大きく4つの改善を進めています。

1．タグの有効活用

これまでMMMではディレクトリルールのみを定義し運用しており、esaの標準機能であるタグはほとんど利用されておらず、新たにこのタグを有効活用する試みを始めています。

タグ付けを必須化することでesa内のディレクトリを跨いで、横断的にドキュメントを辿ることが可能となります。

一つポイントとしては、このタグをセットする際に各自が自由にタグ名を定義するのではなく、必ず社員で議論して事前定義したタグマスターから選択するというルールを設けることで、タグのカオス化をヘッジしています。

2．緩めのディレクトリルール

新たにタグルールを厳密に設けた反面、esa内のディレクトリに関してはある程度緩い階層構造に再定義しました。

具体的には。

- プロジェクト
- 技術情報
  - デザイン
  - フロントエンド
  - サーバサイド
  - 共通
  - その他
- 社内共有
  - 社内制度
  - 勉強会
  - 雑多メモ
- Archive

ようなシンプルなディレクトリとして、大枠でのカテゴリーを第2階層までとしています。

これには『ドキュメント作成時にディレクトリ構造で悩ませない』ことと『タグルールが徹底されていればディレクトリの横断が容易』になるという背景があり、あえて厳密なディレクトリルールを廃止しました。

3．『アーカイブ』ルール(案)

esa上に作成されたドキュメントについては誤って作成した場合や、本当に個人メモなどの場合を除外し、基本的にはドキュメントは削除せずアーカイブさせるというルールを設けています。
※アーカイブはesa標準のArchive機能を活用

どのようなドキュメントをアーカイブするのか？という点については、まだ議論中...の段階ではありますが、案としては

• 過去の資産的なドキュメント(ある時点でのプロジェクト設計/仕様/背景/経緯など)
• 最新情報を確認するだけのREADMEドキュメント(開発環境構築など)

などが現状あがっている状況です。(今月中に制定予定)

4．月に一度のドキュメント整備タイム

月に1度、約1時間程度、全メンバーでドキュメントを整備する活動時間を制定しました。

全メンバーで行う。という点が大きなポイントで、整備をすすめる中でドキュメントを起票したメンバーに直接気軽に聞けるようにという配慮があります。(交代制だとプロジェクトで忙しいメンバーに問い合わせるハードルが高い)

まとめ

社内のメンバーで創り上げられるドキュメント基盤は、社として非常に重要な資産であると考えています。

ドキュメントを有効活用してプロジェクトを円滑に進められるよう、我々MMMはこれからもドキュメント整備に適切な工数を投じていこうと考えていますので、また一年後辺り？に活動のご紹介できればと考えています。

ではでは。

kuni