CLOSE

非同期な開発体制を支えるドキュメント文化(全2記事)

書く側も読む側も大きな負担なく取り組めるドキュメント運用 文化醸成のための3つの取り組みと、4種類の運用ドキュメント

Launchable, Inc.のソフトウェアエンジニアであるこんぼい氏は、ドキュメントを大事にしている理由と、具体的にどのようなドキュメントを運用しているのか、また、ドキュメント文化醸造のための取り組みについて紹介しました。全2回。前回はこちらから。

運用ドキュメント1 Project Proposal

こんぼい氏:ここからがメインパートというか、どんなドキュメントを運用しているのかを紹介していければなと思います。

いろいろなドキュメントがあるんですが、今回は4つ例を持ってきました。1つ目がProject Proposal、2つ目がDACI(Driver, Approver, Contributors, Informed)、Postmortem、CS Investigation Logというかたちで持ってきました。

まず1つ目がProject Proposalですね。読んで字のごとくじゃないんですが、新機能の提案とか仕様の変更とか、プロジェクト/機能改修のスタート地点に書くドキュメントになります。

口で言ってもちょっと難しいのでまず例を見て……。(スライドを示して)先ほど言ったCLI、Python製のツールがあるんですが、そこにAndroidのCompatibility Test Suite、通称CTSというテストフレームワーク。「Androidを組み込んだ時に、そのAndroidがちゃんと動くか?」みたいなテストスイートのプロファイルを追加した時の例になります。

まずヘッダーというか、文章の先頭部分にメタデータを追加します。ステータス、どういう状況なのかとか、誰が提案しているのか、それはいつ提案されたものなのか、それを開発というか推進させるのは誰なのかがファーストビューというか、トップに書かれています。

この場合だと僕がproposeして僕がdriveしている感じなんですが、プロダクトマネージャーがproposeを行ってエンジニアがdriveするようなケースもよくあります。

本文には大きく4つのセクションがあって、Why、 Prior art、What、How。Whyはプロダクトチーム以外に向けて、なるべく一言で概要を説明するセクションになっています。ここではいわゆるエンジニアが使う言葉みたいなのを排して、セールスとかマーケティングとかその他の人たちが、「プロダクトチームはなんで今これをやっているの?」ということを一言で説明する文になっています。

Prior artは、関連資料とか「過去にこういう事例があったけど、なんでこのプロダクトをやるのか?」みたいな時に、「過去の資料はこれです」みたいな感じでセクションに書きます。

Whatはプロダクトチーム向けの概要を書きます。なので、ここではいわゆるプログラミングの話だったり、より詳細なコードベースの話だったり、いろいろなワーディングって言うんですかね。エンジニアのワードが出てもぜんぜんいいし、なぜこれをやるのかという概要をプロダクトチーム向けにより詳細に説明します。

Howはどう進めるかの詳細です。「このコードをいじってこのファイルをやって」みたいな詳細をけっこう書きます。が、コードを書くようなことはプルリクエスト上で議論することもけっこうあります。

これはセクションをまとめて見せたいのでシンプルなページを持ってきたのですが、けっこう複雑なプロジェクトでは2スクロール分ぐらいWhatを書くケースもあります。こういうパターンもあるし、別のパターンもあるしという感じです。

あとはシーケンス図を書いたり、デモのラフなモックを手描きで描いて、それを貼って「こういうイメージです」とすることもあれば、さまざまです。決まっているのは、最初のメタのようなヘッダーの部分と、各項目が決められているということですね。

※ Priority Artと記載されている部分は、本来は Prior artです

プロダクト(について)、先ほど僕はProposalしてdriveしてと言いましたが、プロダクトマネージャー、エンジニア、職種関係なく書きます。

社内では「とりあえずすぐ決まるかな」と思ってミーティングのトピックとして出した話題で議論が白熱すると、「いったんOne Page書いて整理しますか」という発言をよく見かけます。どういうことかというと、複雑なことに対してどうやって進めていくかを書いて、そこでドキュメント上で議論をしましょうという光景がよくあります。

運用ドキュメント2 DACI

次はDACIですね。これは比較的重要な意思決定をする時に書いています。「Driver, Approver, Contributor, Informed」の略です。「誰でもその提案に対してコメントしたり意見を言っていいんですが、意思決定をするのはこの人ですよ」ということが明示的に決められています。背景や関連するデータ、「このDACIをもとに何を決めたいのか」みたいなものを書きます。

(スライドを示して)Python 3.5をドロップしたと冒頭で紹介したんですが、これがその時に書いた実際のDACIになります。影響度がどれぐらいあるのか。誰が進めるのか。このあたりはProject Proposalともかぶるんですが、違うところとしては、Approver、誰が承認をするのか。今回はエンジニアのトップとプロダクトマネージャー、そして今回はお客さんに関係があるので、CSM、カスタマーサポートマネージャーの承認も得ています。「この3人からチェックが受けられてはじめて、そのドロップの作業を行いますよ」というかたちになります。

Informedは、承認者ではないけれども関係者。なので、マスクはしていますが、エンジニアチームに宛ててメンションを飛ばしています。

DACIの中身は、Relevant Data、Background、Option、Action Itemというかたちで、大きく4つ項目があります。関連するデータとして、Python 3.5をドロップした時だと、「今ユーザーがどれぐらいかのアクセスログを見て(みたところ)、Python 3.5を利用している人はいませんでした」という集計データとかを貼っています。

背景としては「もうサポートを切りたいです」という話なんですが、それを一応ちゃんと書いて。オプションとしては捨てるか捨てないかみたいなことが書かれています。捨てないのも手だよねということで一応書いているんですが、できるなら捨てたいというProposalになります。

Action Itemとして承認されたら、コードベースからPython 3.5のコードを消して、新しくshipするということが書かれていますね。

運用ドキュメント3 Postmortem

Postmortemは他社さんでもやっているのかなと思うんですが、障害が起こった際に書きます。

障害が終わったあととか、障害中にやることがないという人は、時系列に「今何やっています」みたいなものをあとから振り返られるように書いています。

ミーティングで問題のリストアップをします。ここで大事なのは、「誰が悪い」とかそういう犯人探しはしないことです。

最後に、日付と担当者をつけてAction Item、何をやるということを書いていきます。一応週1で定例をやっているんですが、そこで進捗を確認して、「これは終わりましたか」ということを確認して、全部が終わるとステータスが完了になります。

運用ドキュメント4 CS Investigation Log

最後はCS Investigation Logですね。これはCS担当と調査担当するエンジニアがコミュニケーションをするために使います。お客さんから何か問い合わせがあって「エンジニア、これをちょっと調べてください」といった時に書きます。

まずCSがページを用意して、CS側がどんな問い合わせをして何を解決してほしいのかを2〜3行書いてくるので、それに対してどんどん追記していきます。

(スライドを示して)これは「2013年の12月20日にとりあえず調べたよ」っていう。「1個1個のやつはいいんだけど、monthlyにするとちょっと計算結果がずれるみたいなバグがありました」、「なので、明日もっと調べます」みたいな、調査の進捗共有とかですね。

解決した場合には「原因は〇〇でした」「こういうことをお客さんに伝えてください」ということをカスタマーサポートに投げ返しています。

これを書く意図としては、進捗共有の見える化もあるんですが、ほかのエンジニアが似たような問題をやる時に、「この人はどうやって調べたんだろう」というナレッジシェアの意味合いもあります。

ドキュメント文化醸造のための3つの工夫

ダーっと説明してきましたが、最後残り5分でどういう運用をしているのかを紹介していこうと思います。

つらつら言ったんですが、「ドキュメントを書くのが大変そう」とか「ドキュメントが見つからないよね」みたいな話がけっこうあるんですが、Launchableはどうやってそこを乗り越えているのか、どういう背景でこういうドキュメント文化が醸造されているのかを紹介して終わりにしたいと思います。

3つ持ってきました。「仕事以外もドキュメント」「箱」「型」ということで説明していきます。

「仕事以外もドキュメント」。まず入社すると、自己紹介を書くところから始まります。オンボーディングなので「仕事やろ?」という感じもするんですが、一応ここでは仕事以外とします。

あと、Rocket Fuel Dayという月1回のリフレッシュDayみたいなのが社内ではあります。例えば過去にあった事例だと、「やったことないことをやってみよう」ということで、僕は「家でパンを焼いてみました」ということを写真付きで書きました。

他にも「探検家になろう」みたいな時は「最寄りの沿線で降りたことのない駅で降りて、ちょっと探検してみました」みたいなものを書いたり、思い出の食事の時については、同僚の社員が、遠距離恋愛中に新幹線で食べる……。確かカツサンドだったかな。「サンドイッチが思い出の食事です」みたいな、すごくハートフルなものがあるんですね。そういうことを書くことがイベントとしてある。それもドキュメントで行われる。

つまり何が言いたいかというと、Launchableではハードルの低いことを書く機会がすごく提供されているなと思います。書くことに慣れる場が仕事以外でも用意されているのが、すごく大きいなと感じています。

次は「箱」ということで、簡単に言うとドキュメントを置く場所ですね。Launchableでは部門ごとにConfluenceのスペースというか、ディレクトリみたいなものが分かれています。

(スライドを示して)左のやつを見ると、下にProductとかRocket Historyとかがあるんですが、それぞれスペースが分かれています。ProductのHomeはけっこうシンプルで無骨な感じなんですが、Customer Successのところは絵文字とかを入れて、ちょっとにこやかになっている。それぞれの部門の特徴がここにも現れます。

先ほど言ったProject Proposalは、Product HomeのActive Initiativeとか、Initiative Ideaとかが置き場になっていて、CS Investigation LogはCS(Customer Success)のInvestigationsという板に置いていきます。

InvestigationはCustomer Successの管理下なので、1年ぐらい経つと、「もう古いから」と言ってがんがんアーカイブされていきます。こんな感じできちんとオーナーシップが決まっています。

最後に「型」の話をして終わります。ドキュメントの型、フォーマットですね。先ほど紹介したドキュメントも、書く項目があらかじめ決まっています。何を書けばいいかはすごく明確だし、どこに何が書いてあるのかが決まっているので、読む側も読みやすいです。

ここまではよくある(ことだ)と思うんですが、フィードバックの型というものもあって。30/60/90% FB。これはTrelloのフィードバックフォーマットを参考にしているんですが、各フェーズに合わせた適切なフィードバックをすることが推奨されています。

他にもフィードバックの仕方で、言い方って言うんですかね。意見/提案/ 委任ということで、このフィードバックがどれぐらいのレベルなのか。

例えば、「in my opinion」、つまり「個人的な感想・意見なんですけど」とか、「これは絶対変えないといけないよ」「これは参考程度に聞いてください」みたいにきちんと前置きしてコメントしています。

なので、フィードバックも「まぁ、確かにそれはちょっと思うけど、in my opinion、個人的な意見だから今回は入れません」とか、そういうことがあります。

書く側・読む側も大きな負担なく取り組めている

時間も時間なので、まとめに入ります。

今回は非同期な開発体制を支える文化ということで、なぜLaunchableがドキュメントを大事にしているのかを、組織面の話とドキュメントの持つ力の両面から紹介しました。

どんなドキュメントを書いているのかというところで、Project ProposalとかDACIとかの実例を持ってきて紹介しました。

最後に、そういうドキュメント文化を醸造するにはどういう背景があるのかなということで、仕事以外にもけっこう文章を書いています。あと、オーナーシップが場所によってけっこう決まっているし、型もあるので、書く側・読む側も、負担なくと言ったら変ですけど、負担を下げて書くことができます。ということを紹介しました。

最後に、Launchableでは絶賛エンジニアを募集しているので、ドキュメントをめっちゃ書きたいエンジニアはぜひ懇親会などで僕に話かけてください。

ご清聴どうもありがとうございました。

続きを読むには会員登録
(無料)が必要です。

会員登録していただくと、すべての記事が制限なく閲覧でき、
著者フォローや記事の保存機能など、便利な機能がご利用いただけます。

無料会員登録

会員の方はこちら

関連タグ:

この記事のスピーカー

同じログの記事

コミュニティ情報

Brand Topics

Brand Topics

  • 孫正義氏が「ノーベル賞もの」と評価する最新の生成AIとは “考える力”を初めて身につけた、博士号レベルを超えるAIの能力

人気の記事

新着イベント

ログミーBusinessに
記事掲載しませんか?

イベント・インタビュー・対談 etc.

“編集しない編集”で、
スピーカーの「意図をそのまま」お届け!