ドキュメント整備に向けて

はじめに

株式会社ココナラのアプリ開発グループiOSアプリチームのさだっち(@tomsan96)です！

いきなりですが、組織・チームにおいてドキュメントはしっかり整備されているでしょうか。
日々すべき業務がある中ドキュメントというものは後回しにされがちです。
そもそも可視化・言語化されていない、ドキュメント化したもののメンテナンスされていない、作成は続けているものの負荷となってしんどいなどの問題は多くの組織・チームが抱えているかと思います。

私たちアプリ開発グループでも同じような問題を抱えており、現在ドキュメント整備の体制を構築しているところです。
今回は私たちが行っている取り組みをまとめました。

背景

2024年入社の新卒メンバーが来るまでに、オンボーディングで使えるドキュメントを用意しておきたいというのが大きなきっかけとなりました。
現在チームでは、オフライン・オンライン問わず「わからないことがあったら気軽に聞ける」という環境ができています。
ただ一方でこれは歴の長いメンバーの存在に加え、新メンバーもある程度知識のある中途採用だったからこそ回っていたともいえます。
そんな中、2023年にココナラ初の新卒採用がありました。
https://blog.coconala.co.jp/n/ncd9bf67cc2a4

ドキュメント整備が進んでいない状態だと、新メンバーと既存メンバーどちらの負荷も高くなることに繋がります。
メンバーの入れ替わりも想定する必要がありますし、会社としても事業拡大が進んでおり今後もメンバーが同じ部署にいるとも限りません。
現在の課題としては以下のようなものがあります。

• 新メンバーがどこにどのようなドキュメントがあるかがわからず困ることがある
• 特定のメンバーの持つ知識に依存し、直接聞かないとわからないことが多い
  • 今後メンバーやチーム構成の変化があったときにわかる人がいなくなる危険性がある
  • 背景が不明なことが多い

こういった要因でドキュメントの重要性が高まっているという背景の元、本格的にドキュメント整備を進めることとなりました。

目指していること

ドキュメント整備を通してどうなっていきたいかを最初に設定しました。
ただ闇雲に作り始めても、「ドキュメントを作っても意味がない」「大変なことが増えるだけ」というネガティブな経験に繋がってしまうため、ドキュメント整備で何を実現したいのか、何を避けたいのかを言語化しました。

実現したい未来

• ドキュメントが価値を発揮してコミュニケーションの効率が上がっていること
  • 「まずドキュメントを探しに行く、それでわからなかった時に相談する」「質問された時にドキュメントのリンクを渡すことで解決する」という流れを増やすこと
• 作成したドキュメントに対してコメントなどのフィードバックが発生し、ブラッシュアップがされること
  • いきなり完璧なものを求めないことで、ドキュメントを書き始めるハードルが下がるという効果を期待

避けたい未来

• ドキュメント作成がメンバーの負荷になること
• 「ドキュメントを作る」が目的になり、作りっぱなしになること
  • メンテナンスされない
  • そもそも読まれない

具体的な取り組み

目指している未来を手に入れるために以下のような流れで進めています。

必要なドキュメントのリストアップ
候補となるドキュメントのリストアップから始めました。
ドキュメントを多く使うのは新しくチームに入るメンバーです。
そのため入社してからの期間が短い(5ヶ月)私が最初に経験ベースで書き出しました。
加えて今年の新卒メンバーを中心に、他のメンバーからもヒアリングをしてリストアップをしていきました。

次に行ったのがドキュメントの優先づけです。
使われないものを作成しないことで、作りっぱなしを防ぎ、かつ作成する負荷を減らす意図があります。
以下のように分類しました。

• 優先度高
  • オンボーディング時に必要となるドキュメント
• 優先度中
  • 使用頻度の高いドキュメント
• 優先度低
  • 使用頻度は高くないがチームの生産性を長期的に高めるために必要なドキュメント
  • メンバーが困っていることを解消するドキュメント
  • 特定のメンバーしか知らない知識/ノウハウ
• 着手なし
  • ほとんどのメンバーが知っている知識/ノウハウ
  • あったら便利なドキュメント(なくてもあまり困りはしない)

ディレクトリ構造やファイル名のルール設定を行う
煩雑なルールを設定すると、ルールを守ることに対して面倒な気持ちが生まれたり、守られないケースが出てきたり、ルールに沿うためのメンテナンスコストがかかります。
そのためどれだけ複雑さを無くすかに注力しました。
ディレクトリ構造も見直しはしたものの大きく変更はしていません。
意識したこととしてはMECE(漏れなく、ダブりなく)が実現されているかどうかです。

ファイル名のルールも最低限です。
具体的には会議系のページ名の先頭に日付を記載すること、同名が発生し得るページ名の先頭に「iOS」「Android」を記載すること(ドキュメント管理ツールとして使用しているConfluenceでは同一ページ名が許容されないため)くらいしか決めてません。
ドキュメントを見つける導線として、検索かディレクトリから選んでいくものがあります。
どちらの場合も単語単位で選択していくのが自然です。
特に検索の場合だと他の部署のドキュメントも候補に引っかかります。
決まったルールでのファイル名かどうかが見つけやすさに与える影響力は低く、細かなルールを守る煩雑さの方が大きいと判断しました。

運用ルールの設定を行う
ディレクトリ構造やファイル名と同様、最低限のルールになるように意識しました。
その上で設定したルールの1つに、ページ作成・編集・アーカイブ時はSlackチャンネルで共有をするというものがあります。
作ったのに誰も気付かない状況を避けるためにも、更新されたことを検知する仕組みを作りたいと考えました。
Slackと連携して自動で通知を受け取ることも可能です。
ただConfluenceの場合、タイトルと更新者のみの情報が通知されるため更新内容についてはドキュメントを見にいく必要があります。
改行や誤字脱字の修正レベルでも通知がいきますし、誰が見るべきものかも判断できません。
そのうち通知が見られなくなる未来が想像できました。
そのためSlackで必要なグループメンションをつけた上で手動で通知してもらう運用を設定しました(誤字脱字レベルは不要)。

このようにメリットデメリットを考えながら、必要であろうルールを設定していきました。

ドキュメントの作成を進める
これが今の段階です。
各メンバーにドキュメントを割り当て、作成を依頼しました。
作成したドキュメントをどのディレクトリに格納するかの指定なども行い、作成時の迷うポイントを少しでも減らすように工夫をしています。

終わりに

本記事ではドキュメント整備のためにどのような取り組みをしているかをまとめました。
皆さんのチームや組織において少しでも参考になることがあれば幸いです。

まだまだこの取り組みは動き出したところです。
半年後、1年後、数年後にドキュメントが作られたのか、そのドキュメントがどんな価値を発揮したのか、そしてドキュメントの文化をチームに根付かせることができるのか。
試行錯誤をしながら走っていきますが、結果についての記事もいずれ書こうと思いますので楽しみにしていてください！

宣伝

現在ココナラではエンジニアの募集を行っております！
ぜひ以下のページからご覧ください！
https://coconala.co.jp/recruit/engineer/