社内の情報共有ツールの見直しとドキュメント整備のための活動

新年度もはじまりましたが、みなさまいかがお過ごしでしょうか。@amymdです。

突然ですが、みなさんは会社ではどのような情報共有ツールを使っていますか？

弊社ではドキュメント管理ツールとしてQiita:Teamを導入しているのですが、運用していていくつか課題が出てきたため、Qiita:Teamの運用方法について見直しを行いました。今回は、その活動内容について報告したいと思います。

ツールを導入したけどうまく活用できていないかも…と考えてる方々への一助となれば幸いです。

情報共有ツール検討会の立ち上げ

オールアバウトのシステム部には、Team Tech Ball (テックボール)と呼ばれる、技術推進ユニットがあります。
これまでどんな活動をしてきたのかは、過去の記事をぜひ読んでいただければと思います。

allabout-tech.hatenablog.com

情報共有ツール検討会が立ち上がった背景は、上記の記事から抜粋すると、

数年前に社内Wiki運用からQiita::Teamへの移行を行い、手順書・仕様書・個人の知見を書く文化は出来ました。一方でアウトプットの質や量は、個人の裁量に任せているところが多く、最高な状態にはイマイチ届いていません。
プロジェクトに新規参加した人も欲しい情報にちゃんとたどり着く！
成長するプロダクトの仕様書のメンテはどうしたら良いか？
どんな情報があると業務がスムーズに進むのか？
以上のような内容を検討、ツールやドキュメント管理方法の見直しを開始しました。

……というような背景から、チームが立ち上がり、まずは現状の課題やドキュメント状況の整理から始まりました。

社内の情報共有ツールにおける現状の課題の整理

課題の調査方法

まずシステム部のエンジニアに対し、現状の情報共有ツールについてアンケートとインタビューを行いました。

アンケート内容
- ツールに対する感想
- 良いところ／不便なところ
- そもそも情報共有ツールはどうあるべき？
- 前職で使ってたツールなど
個別インタビュー
- 調査した結果をもとに数人から意見を掘り下げるため実施

これによりそれぞれが思う情報共有ツールの有り方や、現状の運用方法で抱えている課題の洗い出しを行うことが出来ました。

現状の課題

アンケートや個別インタビューから判明した、主な課題をいくつか紹介します。

1. 目的の情報にたどり着きにくい

社内のQiita:Teamでは、様々なサービスに関する技術的な記事やデプロイ方法の記事、日報、記事録など、多種多様な投稿があります。
そのため、検索結果にノイズが多く含まれてしまい、目的の情報を見つけにくいという問題が起きていました。

2. 共有する情報がバラバラ

記事に記載する情報が異なっていたり、タグ付けが適切にされてなかったりというものがあります。
また、プロジェクトによってはQiita:Teamには情報が無くて、Googleドライブや社内Wikiなど別のツールで管理している…というように、情報が散在しているという課題がありました。

3. 記事のメンテナンスがされていない

現在のシステムではもう使われていない技術の記事や、現在の仕様とは異なる記事、書きかけになっている記事があるため、誤解を招く恐れがあります。

ドキュメント整備に向けたルール作成

これらの課題は、例え他の情報共有ツールに移行したとしても発生し得る問題です。
そのため、今回はツールの移行で解決するのではなく、課題に対する解決策を検討し、運用ルールを少しずつ整備していくことになりました。

f:id:allabout-techblog:20180425110320p:plain:w300

解決策に対し、期待できる効果・導入コスト・運用コストをそれぞれ評価し、まずは下記のようなルールを導入してみることになりました。

目的の情報にたどり着きにくい
- Readmeルール(リポジトリに書くべき情報)
- プロジェクトページ整備
- グループ機能整備
共有する情報がバラバラ
- ツール使い分け指針の周知
- タグ付けルール
記事のメンテナンスがされていない
- 書きかけルール整備
- ドキュメント整備タイム

全てのルールを細かく紹介はしませんが、例えばこれまであまり活用していなかったQiita:Teamのプロジェクトページやグループ機能や、こちらで用意した記事やREADMEのテンプレートを使ってもらうルールを作成しました。

用意したREADMEのテンプレートは、下記のようなMarkdown形式のものを作成しました。

# プロダクト名
プロダクト、リポジトリの一言紹介文(1行)

## 概要
リポジトリの大まかな概要(2~3行)

## 動作環境
主な依存関係を箇条書きで記載。

## 認証
必要な認証情報を記載。  

## ローカル開発環境構築
git cloneしてアプリを起動し、実装するまでの一連の流れをコマンドと共に記載。
Dockerで開発する場合は、コンテナ起動手順も記載。

## ユニットテスト&コード規約のチェック
実行コマンドを記載。

## デプロイ
アプリのデプロイ方法を記載。

ドキュメント整備タイムのトライアル実施

しかし、このドキュメント整備のルールが果たして適切かどうかは実際にやってみないとわかりません。そこで、各グループごとで「ドキュメント整備タイム」のトライアル実施をしてみました。

ドキュメント整備タイムとは

仕事に追われてなかなかドキュメントを整備する時間が取れない…そんな課題を解決するために、月に一度、一時間だけドキュメント整備のための時間を設けることを提案しました。

これは、下記の記事を参考にいたしました。 blog.mmmcorp.co.jp

今回はまずお試しということで、ドキュメント整備タイムを実施してみて、そこでどんな効果があったか、不足しているルールは何かを検討してみることにしました。

実施する際は、ドキュメント整備のルールやドキュメント整備タイムに関する記事を投稿し、システム部全体で共有しました。

f:id:allabout-techblog:20180423184339p:plain

実施した結果・感想を抜粋して紹介

実施してみて、良かったところ・悪かったところをアンケートなどで聞いてみた内容をいくつか抜粋して紹介します。

良かったところ
- 情報を見直すきっかけになる。
- 更新するタイミングを失っていたので、更新できて嬉しい。
- 継続できれば整備方針が固まって時間もかからなくなり、運用に乗りそう。
悪かったところ、分からなかったところ
- どこまでタグをつけたらいいかわからない。タグをつける明確なルール、規則が欲しい。
- タグとグループの棲み分けをどうすべきかわからない。
- まだルールが整備されていないと、悩む時間が多くなってしまう。