📝

【汎用ソフトスキル】ドキュメンテーションの続け方

2022/03/29に公開

Google Docs

documentation

team

idea

この記事の目的

最近「良いドキュメントが作れているな」と思う機会が増えてきたので、その知見をアウトプットしたくなった。

想定読者

今所属してる組織(会社/プロジェクトなど)のドキュメントがイマイチで悩んでいる人
そもそもドキュメントが無い組織に所属していてつらい思いをしている人
「ドキュメントを作れ」という漠然としたタスクを振られて困っている人

想定読者ではない人

メンテなブルなドキュメンテーションのエコシステムが完成している組織で更によいやり方を模索している人
- 私もまだ模索中なので、いいやり方があれば教えてほしいです👀
顧客提出などの「納品が必要」なドキュメントの管理方法を模索している人
- この記事では「社内の情報共有」にスコープを切って話をしています

書いている人のスペック(参考)

歴５年くらいのなんちゃってフルスタックエンジニア
普段は Node.js / React.js or React Native あたりでアプリ制作をしている。たまにインフラぽちぽちする。(I ♡ aws-cdk)
３年くらい所属している会社はドキュメントが必要になる過渡期なので、随分考えることがあった

要約

ドキュメントはなぜは必要か
- ドキュメントは社内資料と議事録と納品物の3種類ある
- 社内資料は「何かの目的のために」書く
- 議事録は「過去の意思決定を記録するために」書く
- 納品物は「作ることがビジネス上必要だから」書く
なぜドキュメンテーションは続かないのか
- ドキュメンテーションのデメリットは「読まれない」こと
- 不要なドキュメンテーションは「同意なく省略」される
続けられるドキュメンテーションとは
- 最初に「誰が/いつ/なんのために読むか」かを決めよう
- 更新をどうする(あるいはしない)ポリシーを決めよう
- 「適当に書く」と「頑張って読む」でバランスを取ろう
- 議事録を活用したコミュニケーションをとろう

ドキュメントはなぜ必要か

ちゃんとしたドキュメントを作るの、みなさん得意ですか？私は大の苦手です。苦手でした。

「仕様なんてどうせそのうち変わるし、そもそも現在の仕様だって認識と違うかもしれない。コード書いたり読んだりした方が速くない？」

とまあ、そんな感じです。 SIer で仕事をしていた経験があり、仕様書作成無間地獄を経験したことがあると、こんな肌感の人は多いと思います。
しかし最近、仕事で関わる人間が増えるに連れて「あー、とりあえずでいいからドキュメント残しとくの大事だわ。。。」と考えを改めていくことになりました。

私は会社で作る文書を大きく3種類に分けて整理しています。
それは社内資料と議事録と納品物です。
まずはそれぞれ、どんなものか見ていきましょう。

社内資料

社内での明確な利用目的を持って作成される
具体例
- 新規システムのキックオフに向けた設計図
- システムリプレイスに向けたDBのER図
- 新入社員に向けた入社後の手続き一覧
- プロジェクトに新規joinするメンバーに向けたプロジェクトの解説資料
必要に応じて更新されることもある
- 必要が無いと大抵更新されなくなる
メリット
- 議事録を直接読むより素早く現状を認識することができる
  - 主な用途は「認識合わせ」である

議事録

合意内容の記録が目的
会議の内容を可能な限りそのまま記録する
一度書いたら基本的に更新はしない
メリット
- 過去にした議論を蒸し返して時間を浪費することを防げる
  - 逆に、過去の前提が覆ったときに「再議論が必要である」ことを素早く認識できる
- 決定に至った経緯を知ることができる
  - 不自然な実装を廃止する時などに「この実装を廃止してもよい」という根拠を持てる
「合意内容の記録と確認を目的とした社内資料」とも言える

納品物

社外の関係者に提出する必要がある文書
常に正確さが求められる
具体例
- 受託案件納品のための仕様書
- 確定申告の書類
- 請求書やら領収書やら
メリット
- 作成するとお金や権利や承認がもらえる
- 作ることそのものに価値がある(できるだけ作りたくはない)

大体こんなところでしょうか。私が勝手に整理した概念なので、厳密なものではないです。
なお、今回の記事では「納品物」については今回は触れません。(大抵の場合、粛々と作る以外に特に対策が無いからです)このあと、ドキュメンテーションという言葉の対象にするのは議事録と社内資料のみにします。

このように整理すると議事録にせよ社内資料にせよ、プロジェクトを勧めていく上で有用であるのは間違いないように思えます。
しかし、「議事録が上手く残っていない」「wikiが荒れ放題になっている」というのは、誰もが目にした光景です。なぜなのでしょうか。

なぜドキュメンテーションは続かないのか

それは、ドキュメント作成には「徒労に終わってしまう」という大きなデメリットがあるからです。
具体例を見てみましょう。

アンチパターン: とあるプロジェクトのwiki

とあるプロジェクトの例を交えて考えてみましょう。
5年ほど保守が続けられたPlay Framework製の業務システムで、至るところに無理のある実装やハックが施されています。
「ドキュメントはgithubのwikiを更新していく」というポリシーが決まっています。「環境構築手順」「ER図」「システム概要」などの項目がありますが、そのほとんどは更新されていません。新メンバーが増えた際に「環境構築手順」がわずかに更新されるくらいでしょうか。不可解な実装が多く、実装中に仕様不整合の手戻りが発生することが多々あります。全貌を把握することは古株のメンバーにももはや出来ず、wikiを更新しようにもどこから手を付けて良いのかわからない。リプレイスもそろそろ考えたいがそれを議論するための情報もない。。。

やや極端な例ですが、わりとよくある話ではないでしょうか。(書いてて辛くなってきました)

もちろん、このような状況に陥る開発計画にも問題があるでしょう。しかし、実装に伴って「githubのwikiを更新していく」という作業を続けられていれば、ここまでシステムの理解が難しい状況には陥らないはずです。

その解決のヒントは、このwikiの唯一更新されている場所にあります。このような惨状に陥ったプロジェクトでも大抵の場合は 環境構築手順だけは更新される 事がしばしばあるということです。「環境構築手順」以外が使い物にならないwikiや資料、みなさんも見覚えがないでしょうか？なぜこのようなことになるのでしょうか？

それは、環境構築手順だけが唯一、「主に新規参画者が環境構築のために最初に読む」という利用目的がはっきりしているから です。

不要なドキュメンテーションは「同意なく省略」される

優秀な人間は「無駄かもしれない」という公算が高いものにはコストを掛けません。議事録にせよ社内資料にせよ、利用される公算のないドキュメントはいずれ同意なく省略されてしまいます。
(これは、多くの場合「なんとなくいらない空気になった」という形で、明確な合意を経ずに行われます)

プロジェクトのwikiはその最たるものです。
大抵の場合、wikiは「プロジェクトに所属する関係者に向けて」「わかっていることを書く」という方針で運用されてしまうことが多いです。これは、実は大変難易度の高いことを要求しています。「新規メンバーと古株メンバーの両方がわかりやすく」「プロジェクトの全体についての情報を書く」ことが必要になるからです。読み手の習熟度やレベルも時間に応じて変化していきます。メンバーの成長や入れ替わりにより、絶えず必要な情報は変化します。それらの状況に合わせて、日々変化するプロジェクトの状況についてのサマリを作り続けることはほとんどのプロジェクトでは割に合いません。
そうしてドキュメントの多くは新規メンバーには情報が足りないが、古株メンバーには不要なものになりはて、最終的にはコードを読んだほうがマシということに陥ります。

あなたのプロジェクトのwikiが更新されないのは、あなたやあなたの同僚が優秀であれば自然なことなのです。

ドキュメントは「作ること」「読むこと」に意味があるのではありません。
ドキュメントのゴールは プロジェクトの現状を素早く共有する ことが目的です。
誰がいつ使うのかを明確にすることが、ドキュメンテーションを続けることの第一歩です。

続けられるドキュメンテーションとは

それでは、以上を踏まえてどうやってドキュメンテーションを続けていくのかについて、ポイントに分けて考えて行きましょう。

目的を明確にしよう

社内資料にせよ議事録にせよ、定義で目的について強調しているのは前章の例のとおりです。先のプロジェクトAのケースだと「環境構築手順」だけは明確な利用目的を持っているため、社内資料として自然に更新が続けられていたのです。
ドキュメンテーションを続けるポイントはここにあります。「wiki」「手順書」「仕様書」などのフォーマットベースではなく、常に目的を念頭に追いて作成する必要があります。

おすすめしたいのは、ドキュメント作成前にドキュメントを利用するイベントを設定することです。
システムリプレイスに向けたDBのER図作成であれば、リプレイスに関するMTGを設定してしまうのです。日付や時間などを予め抑えるのが難しければ、仮押さえするだけでもOKです。

誰が読むのかがわかり、情報粒度の調整ができる
いつまでに必要なのかが決まり、クオリティの調整ができる
絶対に利用されることが確定するので、作成のモチベーションが上がる

など、メリットは様々です。(個人的には3が一番大事だと思います)
誰がいつ活用してくれるものなのか。 これを意識し続けましょう。

更新ポリシーを決めよう

「常にドキュメントが事実と乖離しないように更新する」というのは、大抵の場合割に合いません。
目的に沿った最低限の更新にとどめ、ある程度の乖離は明示的に許容する ことが大切です。

例えば「新規joinするメンバーに向けたプロジェクトの解説資料」は、毎月新規メンバーが参画するプロジェクトであれば、無理なく最新の状況に更新されていくでしょう。しかし、「2年に1度しか新規メンバーが参画しない」プロジェクトであれば、解説資料を毎月更新するのは割に合いません。新規メンバーの参画が決まったタイミングで更新されるのが適切でしょう。

大切なのは明示的に許容することです。「この資料はいつまでの時点の情報がわかればいい」というポリシーは、ドキュメンテーションが同意なく省略 されることを防ぎます。目的を明確にし、目的以上のものを作らないことは、プロジェクトのモラルを維持するという観点でも重要です。
エンジニア的に言うと「割れ窓を作らない」ということになるでしょううか。一度も読まれないドキュメントを作成/更新するほど苦痛な業務はありません。

「適当に書く」と「頑張って使う」でやっていこう

ドキュメンテーションの難しい点として、「読むよりも書くほうが大変であるが、読む人が書く人よりずっと多い」ということが挙げられると思います。
書き手はつい、「沢山の人が読むから」ということで読みやすさや正確性、情報の多さにこだわりがちです。結果、ドキュメントの作成/更新にかかる負担が大きくなってしまい、そのドキュメントに関する対応が同意なく省略されてしまうケースもよく見かけます。
なので私は、ドキュメントは書き手は「適当に書く」ことを徹底し、読み手は「頑張って使う」技術を覚えることを推しています。

私が意識している「適当に書く」方法は以下のとおりです。

「ずっと使えるものを作ろう」とするのをやめる
- 必要であれば自然とそのドキュメントは洗練されていく
フォルダを正確に分類するのをやめる
- 正確なルールに基づいてドキュメントを配置するのは大抵労力の割にあわない
- 権限管理のルールだけ守ってあとはフラットに配置する
最新の状態に保とうとするのをやめる
　- 内容が正確で、タイムスタンプがあれば更新はされていなくてもよい
　- 陳腐化しても「更新時点の情報をまとめたドキュメント」として活用できる

後半の「頑張って使う」については、頑張るのは私やチームメイトやあなたではなく、ツールです。
私が今所属してるプロジェクトは主にGoogle Workspace(docs/spreadsheet)を使ってドキュメンテーションをしています。おそらく最もポピュラーなドキュメントツールですが、私はこれをとても気に入っています。
その理由の大きな一つになっているのは、Google Cloud Searchの存在です。

これは平たく言うと、これは「google driveをググる」ことができるツールです。
検索エンジンを使えば、「社内向けgoogle driveから信頼できそうな情報を探してくること」は難しいことではありません。「適当に書く」をしたドキュメントは、それだけで大変有効な情報源に変貌します。多くの人が「適当に書く」をしやすいソフトウェアであることもプラスポイントです。
Business Standard以上のGoogle Workspaceを契約していれば利用できるので、使える人は是非試し見て見ください。

もちろん、検索機能が付いている他のドキュメンテーションツールを使うのでも良いです。
ただし、「ドキュメンテーションツールを併用する場合、検索機能は一つに統合できるようにする」ことを強くおすすめします。検索機能が統合出来ないと、「どっちのツールに記録されていたのか調べる」という手間が発生し、あなたやチームメイトがドキュメントを「頑張って使う」ハメになります。

議事録を活用したコミュニケーションをとろう

社内資料に比べて、議事録は目的を明確にするのが難しく「現在のサマリだけまとまっていればいいや」ということになり、同意なく省略されてしまうことが多いと思います。

これにも、前項の検索ツールの活用が効果的です。「昔どこかでこんなこと話した気がするけどいつだったかな。。。」といったときに、キーワードで検索して議事録を漁り、皆で確認しましょう。
議事録を残していれば、当時の議論や決定事項を見つけて参考にすることができます。議事録を残し忘れていた場合でも、議事録を残しておけばよかったという強いフィードバックを得ることが出来ます。
いまある議事録を有効活用しつつ、議事録作成の習慣をチームに定着させることが出来るのです。
議事録もなんのために作っているのかを理解するのが、ドキュメンテーションを続ける秘訣です。

おわりに ~ドキュメンテーションとは「文明」である~

さて、「ドキュメンテーションを続ける方法」としては、私が言語化できることについては出し切ったと思います。

ちょうど今、黎明期~発展期のベンチャーの成長を経験している身からすると、「ドキュメンテーションって文明だなぁ」というポエムを言いたくなるのでオチ代わり少々くだらないお話を。

確か中学の頃、塾の社会の先生が「文明というのは、文が明らかにする」のだから、文明はすべて文字という技術を持っている」みたいな小話をしてくれました。特に出典もないので、それが本当かどうかはわかりません。しかし、その小話が最近の私には大変しっくりきます。
少人数で発足したベンチャーは、大抵文字の存在しない原始時代を経験しています。エンジニアがプロジェクトに一人だと「エンジニアに向けたドキュメントを作る」ということは原理的に不可能ですし、する必要もありません。自分に向けたメモくらいは残すかもしれませんが、コード上のコメントでこと足りてしまうでしょう。私もほとんど一人でプロジェクトを回す時期があったので、ある種「文明を持たない」エンジニアであった時期がありました。
しかし、プロジェクトに人が増えるにつれて、「それでは都合が悪い」ということを身をもって体験することが出来ました。チームに一定以上の人間が増えるにつれて、自然とドキュメントが作られるようになっていったのです。ちょうど人類が文字を獲得したように、チームが文明化していきました。
この文明化前/後を両方体験できたのは、今回の記事に大きな影響を与えていると思います。
ドキュメントにせよ文明にせよ、人間は必要だから/必要とされているからそれを作る。そういうものであって、そうでしかありえないだろうなぁと、私は思います。