1年かけてAnewsのドキュメントを改善した話
エンジニアリングユニットの酒井といいます。 昨年の9月に入社し、Anewsの開発に従事しつつ時々SREっぽいこともしています。 今回は、自分が入社当初から改善したいなぁと考えていたAnewsのドキュメントについて、これまでやってきた取り組みについてお話しできればと思います。
取り組みを始めたきっかけ
そもそも自分は組織開発において、ドキュメントが重要だという認識がありました。それはこれまでの経験則によるところもありますし、『Googleのソフトウェアエンジニアリング』中で以下のような言及があり、重要性を再認識したというのもあります。
10.2 何故ドキュメンテーションが必要なのか p220:
ドキュメンテーションは長期的に見ると決定的に重要であり、決定的に重要なコードにとっては特に、組織がスケールするのに伴い途方もない恩恵をもたらす。
テストを書くことは普通になりつつありますが、ドキュメントに関してはまだまだな印象が個人的にはあります。書籍では以下のように言及されており、テストと比べると優先順位が下がってしまうのが理解いただけるのではないでしょうか。
10.2 何故ドキュメンテーションが必要なのか p218:
ドキュメンテーションの恩恵は全て下流で生じるため、ドキュメンテーションの作者は通常、直に恩恵にあずかれるわけではない。[…]すぐにプログラマーの利益になるテストと違い、ドキュメンテーションは通常、より多くの労力が前もって必要で、後になるまで作者に明確な利益をもたらさない。しかしテストへの投資同様に、ドキュメンテーションに行われる投資は、長期的には回収できる。
またStockmark内部の話でいうと、比較的短いスパンで組織の動きが発生しており（ちなみに自分はこれまで4チームに在籍していました）、他方エンジニアも徐々に増えてきていました。それもあって、そう遠くないうちにドキュメントの重要性が高くなるなと自分は考えていました。 また元々Anewsの開発においては、PRDは作成されており、エンジニアが設計書を書くこともそれなりに行われていました。オンボーディング時も丁寧にフォローしていただいて困ったことはなかったのですが、開発を進めていくにつれて、欲しい情報にアクセスしにくいと感じることが徐々に増えてきていることに気づきました。
こういった状況もあり、まずは自分だけでちょっとづつ進めてみることにしました。ちなみにやるにあたってはドキュメンテーションに行われる投資は、長期的には回収できるという言葉にもあるとおり、すぐに効果のでるものでもないので、長期戦覚悟で取り組み始めました。
どのように進めたか
闇雲にドキュメントを作っていってもだめなので、いくつか段階を踏みながら進めていきました。
1. どんなドキュメントが足りないのか整理する
まずはそもそも我々には何が足りないのか整理するところから始めました。『Googleのソフトウェアエンジニアリング』の中ではドキュメントには5つの類型があると書かれています。
10.5 ドキュメンテーションの類型 p226:
● コードのコメントが含まれたリファレンスドキュメンテーション
● デザインドキュメント
● チュートリアル
● 概念的ドキュメンテーション
● ランディングページ（landing page）
Stockmarkでは会社の様々な情報をNotionで管理しています。開発用のドキュメントも同様で、PRDや設計書もNotionで管理しています。また各リポジトリのREADMEもしっかり機能していました。しかし概念的ドキュメンテーションやチュートリアル、ランディングページは存在しない、もしくは品質的に十分でない状況でした。そこでまずはこの3つのドキュメントを作成もしくはブラッシュアップすることに決めました。各ドキュメントがどのようなものなのかは後程説明します。
2. 対象読者とそのゴールを決める
対象読者とそのゴールを決めるのは重要です。『エンジニアのためのドキュメントライティング』では1章丸々使って、読者の理解に関するポイントを詳しく説明しています。対象読者やそのゴールが決まってないと記載内容がぶれてしまうので、更新をし続けていくうえでも、誰に向けた何のドキュメントなのかをはっきりさせておくことは重要です。 作成すると決めた3つのドキュメントに対して、以下のような対象読者とゴールを設定しました。
チュートリアル
- 対象読者：新たにジョインしたメンバー
- ゴール：Anews開発で必要な最低限の知識を習得できること
概念的ドキュメンテーション
- 対象読者：Anewsのエンジニアメンバー全員
- ゴール：Anewsの概要と主要機能についての知識を習得できること
ランディングページ
- 対象読者：Anewsのエンジニアメンバー全員
- ゴール：Anewsの開発・運用で必要な情報がどこにあるのかわかること
3. どこに作るか決める
ドキュメント専用ツールを自分たちで運用するのも一案ですが、管理するものを増やしてまでやるメリットが見いだせなかったので、既に我々が使っているツールで追加の運用コストがかからないものを選択肢として考えました。そうすると我々の場合だと、GithubかNotionが候補となります。この2つを比べた時に以下の理由により、Notion上に構築することに決めました。
- ドキュメントOwnerにリマインドする機能がある
- リッチなUIが簡単にできる
- 記法に縛りがある
以下でそれぞれについて詳細を説明します。
ドキュメントOwnerにリマインドする機能がある
ドキュメントは更新され続けることが重要です。それを補助する機能としてNotionのWikiには、ドキュメントOwnerに一定期間毎にリマインドする機能があります。 NotionのページをWiki形式に変換すると、配下のページにOwnerとVerificationを設定することができます。Verificationは認定マークみたいなもので、以下のように、いつまでこの認定マークを有効にするかを選択することができます。
この期限が切れたらOwnerにメールや画面上で通知が飛びます。 この機能によりOwnerが更新を忘れるといったことを防げるのではないかと考えました。
リッチなUIが簡単にできる
Markdownだけでは表現が難しいリッチなUIが、Notionだと簡単に作成できます。またデザインに迷ったらテンプレートも豊富にあるため、それらを真似することも可能です。ちなみにNotionの普通のページをWiki形式に変換すると、それっぽいページに変換してくれます。自分のようなレイアウトを考えるのが得意でない人にとってはめちゃくちゃありがたい機能です。
記法に縛りがある
Notionは記法にある程度縛りがあります。Notionの記法に則って書くことで、ドキュメントに統一感が生まれやすくなると考えています。 個人的に気に入っているのは、見出しが3階層しかないのでネストが深い文章が書けないようになっている点です。例えばこれをMarkdownでフリーフォーマットで書くと、いくらでもネストが深くできてしまうので、読み手に取って見づらくなってしまう可能性があります。
4. どんなものを作るか決める
それでは3種類のドキュメントを具体的にどう作っていったかを説明したいと思います。
チュートリアル
開発環境の構築手順についてはREADMEに記載がされていました。ただ皆さんもご存じの通り、コードを書く環境が整っても実際の開発が進められるわけではありません。 チュートリアルには、新たにジョインしたメンバーが、機能をリリースするにあたって知っておくべき手順や情報が必要です。各種ツールの設定やアカウントの作成、開発フローやそれに伴う手順があれば、それらは必ず知っておく必要があります。また別のチームのメンバーと協業しながら進める場合は誰がどのチームにいるかを把握しておく必要があるかもしれません。これら鑑みて以下の内容を説明するドキュメントが必要だと考えました。
- チーム体制
- タスク管理
- ブランチ運用ルール
- リリース手順
- 日々の運用上のルール
概念的ドキュメンテーション
『Googleのソフトウェアエンジニアリング』の中で概念的ドキュメンテーションについて次のような説明がされています。
10.5.4 概念的ドキュメンテーション p232:
リファレンスドキュメンテーションを読むだけで得られるよりも深い説明や知見を要するコードもある。そのような場合、APIやシステムの概観を提供する概念的ドキュメンテーションが必要だ。[…]例としては、普及しているAPIのライブラリーの概観、サーバー内のデータのライフサイクルを説明するドキュメント等がある。[…]概念的ドキュメントは全エッジケースを対象に含めて扱う必要はない（リファレンスはそうしたケースを対象に含めて入念に扱うべきだが）。
上記内容や先ほど定めた概念的ドキュメンテーションのゴールから、以下のものを作成することにしました。
- Anewsのシステム構成の概要説明
- Anewsのドメインの説明
- Anewsの主要機能であるフィードについての説明
- 認証・認可や通知など共通的な機能だけど全体の仕組みを把握するのが難しそうなものの説明
この他にもあった方がいいなという思うものは沢山ありましたが、作りすぎても更新するが大変なので、まずは最低限に抑えてこれらだけにしました。
ランディングページ
『Googleのソフトウェアエンジニアリング』の中でランディングページについて次のような説明がされています。
10.5.5 ランディングページ p233:
ランディングページが必ず目的を明確に特定しているようにし、それからさらなる情報を得るための他ページへのリンクのみを含めるようにするのだ。もしランディングページ上で交通整理の警官以上のことをやっているものが何かあったら、そのランディングページは本来の仕事をしていない。
大事なのはどのようなリンクを含めるかです。 対象読者は新たにジョインしたメンバーだけでなく、ある程度Anewsの開発に慣れているメンバーも含まれます。開発から運用全てで必要な情報のリンクを含める必要があるので、4つのエリアに分けてそれぞれリンクを張ることにしました。以下は実際のランディングページです。
左上のエリアは新たにジョインしたメンバー向けのエリアとし、チュートリアルのリンクを配置しました。 その他のエリアについては全メンバー向けのエリアです。 真ん中のエリアには設計書のリンクを配置していますが、これは開発するうえで設計書は一番参照頻度が高いので、一番目につく位置に置くことにしました。また、目立つところに置くことで、新たにジョインしたメンバーに対して設計書を書くという行為が自然と行われるようになることを期待しました。ちなみに設計書は元々別のNotion Databaseに作成していたので、そのテーブルビューを表示するようにしています。 左下のエリアには概念的ドキュメンテーションのリンクを、右のエリアは運用に関するドキュメントのリンクを配置しました。運用に関するドキュメントもNotion Databaseで管理されていたので、テーブルビューを表示するようにしました。
5. 誰が作るか決める
ランディングページはこの活動を推進している自分が作るとして、その他のチュートリアルや概念的ドキュメンテーションを全て自分一人で作成するのは、長期戦を覚悟していたとはいえさすがに時間が掛かりすぎると考えました。また今後のドキュメントの更新作業のことを考えると、他のエンジニアメンバーにOwnerになってもらい、以降の更新作業をお願いするのが適切だと考えました。 また既にベースが出来上がっているドキュメントもあったので、それは自分がまとめてブラッシュアップすることにしました。
ドキュメントのOwnerは基本的に立候補で決定でき、一部残ったもので自分より適切な人がいると判断したものは、Ownerになってもらうように直接お願いし、自分でも書けそうだと判断したものは自分がOwnerになりました。 Ownerはとてもスムーズに決まったので、協力してくれたメンバーにめちゃくちゃ感謝しています。
やってみてどうだったか
ざっとこのような流れで取り組みを進め、1年弱かけて計画してたものは全て完成しました。元々長期戦で細く長くやっていこうと思っていたので、1年弱という期間は個人的には想定内でした。 取り組みを振り返ってみて、狙い通りいったものが多かったように感じます。
ランディングページが想定通り機能した
ランディングページは元々あったページをブラッシュアップする形で進めましたが、変更前後でアクセス数がガラッと変わり、ランディングページとして機能していることがわかります。 以下はランディングページのアクセス数の推移です。
Ownerへのリマインドが効果的だった
最初はリマインドが効果的に働くか不安でしたが、実際には各Ownerによりドキュメントが継続的に更新されている状況ができていました。今後もこの流れが継続されることを期待しています。
ドキュメント作成文化の醸成
特に設計書の作成に関しては、新たにジョインしたメンバーにも設計書を書く文化が自然と根付いていると感じる場面が多々ありました。これは自分が思っていた以上に早く効果が出たと感じています。このような結果は、Stockmarkの企業文化やエンジニアメンバーの人柄によるものが大きいと感じており、支援的で協力的な環境で働けることに、改めて大大感謝しています。
課題
現状概ねいい感じで進んでいるのですが、課題もあります。
ドキュメントの有効性が測定しづらい
ドキュメントの有効性を理解するためには、各ページの利用状況を測定することが重要ですが、これが結構難しいと感じています。 利用されていないページは、読者のニーズに応えていない可能性が高いため、そのようなページに関しては内容を見直す必要があるかもしれませんし、場合によっては不要であると判断し削除することも必要です。
Notionは各ページのアクセス数が簡単に確認できるので、ランディングページの場合は一定の有効性を測定することが可能です。しかし、概念的ドキュメンテーションやチュートリアルの場合、毎日アクセスするようなものではないので、単純なアクセス数だけでは有効性を測るのは難しいです。対象読者の母数が多ければ評価可能なのかもしれませんが、我々はまだそういった状況ではないので、どう測定するかは難しいところです。対象読者がそのドキュメントを実際に価値あるものと感じているかを確認するには、直接聞くか何か別の仕組みを導入する必要があると考えています。
まとめ
ドキュメントは単なる文書ではなく、組織の知識共有と効率的なコミュニケーションを促進する上での重要なツールです。特に我々Stockmarkにおいては、リモートワークを基本としているためより重要になってきます。 今後もこのよい文化が継承されるように、継続的にドキュメントを更新していき、課題の解消に向けて、対応を検討していければと思っています。
