ドキュメントはエンジニアリングの始まり

どうも、エンジニアのgamiです。

僕は仕事柄、ドキュメントをよく書きます。

SaaSプロダクトのテクニカルサポートをやっていると、プロダクトの仕様をまとめて公開する機会が多々あります。また、社内向けに業務フローを型化して手順書のようなものを作ったり。

なので自分の仕事について紹介するときも、ドキュメント作成の話をよくします。他方、「ドキュメント書いてます」と言うと、単なる雑務だと思われがちです。たとえば「プログラミングしてます」と比べても、誰でもできるやってもやらなくても変わらない作業であるような印象を与えることがあります。

僕個人としては、ドキュメントを書くことを、ソフトウェアを開発したり使ったりすることと同じくらい、とても重要視しています。今回は、「ドキュメントを書くこと」とエンジニアリングの関係について考えてみましょう。

「ドキュメント」への悪しきイメージ

すでに書いたように、少なくとも日本の多くの職場ではドキュメントは軽視されがちです。生産性への意識が高い人ほど、ドキュメント作成を無駄な作業だと思ってしまいます。そこには、「言い訳づくり」のために作られるドキュメントがあまりにも多いという背景があります。

たとえば、僕が富士通で働いていたとき、丸3日間もかけて大量のExcelファイルを紙に印刷し続けたことがありました。システム受託開発の現場では、開発したシステムだけではなく、その仕様をまとめたドキュメントの納品を求められることがあります。もちろん、家電を買ったらマニュアルが付いているように、システムにも最低限のドキュメントは必要です。しかし、開発プロセスで発生した全てのドキュメントの提供を求められることも多く、その量は膨大になります。ここでのドキュメントの主な役割は、「ちゃんと仕事してます」と示すためのエビデンスです。エビデンスのためのドキュメントを大量に作っていると、価値実感が薄れて心は摩耗していきます。

システム開発に限らず、社内の偉い人を説得するためだけに資料をまとめたり、マイクロマネジメントのための日報を書いたり、価値を感じにくいドキュメントはたくさんあります。実際、僕自身も数年前までは「ドキュメントなんて作るだけ無駄でしょ」と思っている節がありました。

良いドキュメントは不確実性を減らす

今の仕事では、それまで以上に様々なドキュメントを書くようになりました。たとえば、利用者向けにプロダクトの仕様や使い方を説明するための記事をサポートサイトにたくさん書きました。

KARTEサポートサイト

社内ドキュメントには、業務フローやTipsをまとめたり、所属チームの紹介記事を書いたりしました。

こうした仕事の中で、ドキュメントの価値や多様性をやっと理解できるようになりました。

そもそもドキュメントを書くということは、コミュニケーションの手段の1つです。同じ内容を、対面や電話で直接相手に説明することもできます。

こうした口頭での説明と比べて、ドキュメントで情報を伝えることのメリットは、次のようにいくつもあります。

・説明内容のブレを減らせる
・スケールできる
・非同期的に伝えられる

多くの社員が同じ内容をそれぞれ口頭で説明すると、その内容は少しずつブレます。誰もが同じドキュメントを見るようになれば、そのブレを最小限にすることができます。

また、何度も同じことを説明すればそれだけコストがかかります。たとえば顧客向けの説明内容であれば、顧客の数が10倍になると口頭での説明コストも10倍になります。ドキュメントをばら撒くだけで済めば、顧客数が増えてもコストはあまり変わらず、スケールできます。

口頭でのコミュニケーションは、相手と時間を合わせる必要があります。ドキュメントであれば、自分がそれを書く日時と相手がそれを読む日時にズレがあるのが普通です。非同期コミュニケーションには、ドキュメントは欠かせません。

うまくドキュメントを活用できれば、効率的に不確実性を減らすことができます。不確実性を減らすことがエンジニアリングの本分であるのなら、良いドキュメントを書くこともその一部であるはずです。

「ドキュメントっぽさ」のグラデーション

ここまで「ドキュメント」の一語で一緒くたにしてきましたが、どこまでを「ドキュメント」と呼ぶかというのも難しい問題です。

コミュニケーションチャネルの具体例をいくつか挙げてみます。

・電話
・会議
・電子メール
・チャット
・Wikiなど社内ドキュメントサイト
・Wordやパワポなどの文書ファイル
・紙の仕様書や手順書

これを見ると、電話や会議は「ドキュメント」では無さそうですが、テキストで送られる電子メールやチャットはドキュメントっぽさが少しあります。

そのドキュメントっぽさについてあえて言語化してみると、次のような特徴を指しているように思います。

・主にテキスト形式で記録されている
・長い間参照し続けられる
・検索性が高い

たとえば電子メールは、テキスト形式で記録され、過去のものを後から見ることもできますが、大抵は整理されておらず検索性は低いです。社内Wikiなどは、長く参照されることを前提に、カテゴリが整理されていたり検索機能が付いていたりします。よりドキュメントらしいといえます。

このように、ドキュメントっぽいものにもグラデーションがあります。口頭の同期的なコミュニケーションを一部ドキュメントに置き換えるとしても、全てをWordファイルやGoogleドキュメントに置き換えるべきという話ではありません。ドキュメントっぽいもののグラデーションの中で、状況に合わせて適切なチャネルを使い分けていく必要があります。

ドキュメントを扱うSaaSプロダクトの多様化

ドキュメントっぽいものにグラデーションがあるように、それに対応するドキュメント管理ツールにもグラデーションがあります。特にNotionに代表される簡単に使い始められるSaaSプロダクトの増加が目立っています。なお、SaaSプロダクトの方がドキュメントの管理や利用をする上で有利な点がたくさんあることは、以前にこのnoteマガジンでも書きました。

僕の今の職場でも、ドキュメント（っぽいもの）を管理する用途だけでもたくさんのSaaSプロダクトが使われています。

・Notion: 社内向けドキュメント全般
・Dropbox Paper: 一時的に共有したいメモなど
・GitHub: タスクに関するテキスト
・Slack: 流れても問題ないテキスト
・Contentful: 社外向けサポートドキュメント
・...

ツールには、その価値を引き出すための適した使い方や状況があります。「これをドキュメントに残そう」とか「頭の中にあるものをテキストに落とそう」と思ったときに、どのツールを使うべきか。その判断ができるようになることも、一つのデジタルリテラシーかもしれません。

「自分しか知らない知識」を吐き出す

ここまででドキュメントの価値と多様性についてわかりました。じゃあドキュメントを書く習慣を身につけよう、という話になるわけですが、どこから始めればいいか見当がつかないかもしれません。

まずは、「職場であなたしか知らない知識」をまとめたドキュメントを作るのがおすすめです。言い方を変えると、あなたが来月いなくなっても最低限の仕事が回るように、予め引き継ぎ資料を作っておくのが重要です。

誰もやったことがない仕事を始めたとき、その仕事は多かれ少なかれあなたに属人化します。知識やノウハウをリアルタイムに全てテキスト化して公開するのは、不可能で非効率です。

一方で、仕事の進め方が固まってきた後は、属人化を薄めた方がリスクが下がります。状況や学びを同僚に共有することで、担い手をスケールさせ、あなたが倒れても仕事が回る状況を作ることができます。

システム開発の世界でも、開発当時の担当者が全員辞めていてドキュメントも無くシステムの仕様を知る術がない、みたいな話はあるあるです。今動いているシステムを紐解いたり、同時の話を噂レベルで知る人の話を集めたりして、泥臭く仕様を把握する必要があります。もはや考古学の世界です。

ドキュメントを書く習慣が無い人は、来月仕事を辞めても大丈夫なように、頭の中の重要な情報を公開するところから始めてみましょう。

質問への回答をドキュメントで返す

「質問されたらその回答をドキュメントで返す」というのも、ドキュメントを書く習慣を付けるために有効な手段です。僕も今の仕事でよくやります。

ある領域を仕事で任されるようになると、その領域について社内の色々な人から質問されるようになります。そのとき、毎回MTGや電話で説明していては、お互いの時間がもったいない。誰もがいつでもその知識にアクセスできるように、よく訊かれる質問は社内ドキュメントとしてテキスト化すべきです。もしそのドキュメントを検索で見つけてくれる人が増えれば、わざわざ「質問する」というステップを踏まなくても済むようになります。

一方で当然ながら、ドキュメントを作るのは時間がかかるという問題もあります。目の前の質問にすぐ答える方が短期的には楽なので、ドキュメントを書くことを後回しにしがちです。

そこで、自分の中で「2回同じ質問をされたら直接返答するのではなくドキュメントを作ってそれを渡すようにする」というルールを決めておきます。そうすることで、日々の仕事の中で自然とFAQをドキュメント化し続けられます。

プログラマーの三大美徳は、「怠慢、短気、傲慢」だと言われます。怠慢な態度で長期的に楽ができるように自動化を頑張るのは、生産性を重んじるエンジニアらしさの1つです。

質問に直接答えないでドキュメントを返すというのは、失礼な感じがするかもしれません。しかし、「私の時間を奪わないでくれ」という態度でドキュメントのURLを返すbotのように振る舞うことは、まさに良い怠慢といえます。もちろん相手との関係性や状況次第ですが、多くの人の疑問をドキュメントを介して半自動的に解消できるようにすることで、空いた時間をより価値ある使い方に振り分けることができるはずです。

人ではなくドキュメントに学びを蓄積する

このnoteも4,000字を超えて長くなってきました。ドキュメントに対する思いが強すぎます。最後に1つだけ書かせてください。

多くのドキュメントは、書いて終わりではありません。テキストは時間が経つにつれて古くなり、現実から乖離していきます。変化しないソフトウェアが価値を失い使われなくなるように、変化しないドキュメントも価値を失い誰からも信じられなくなります。

ドキュメントが時代遅れになる作用に抗ってそれらをメンテナンスし続けることは、学びのプロセスをみんなで共有するということでもあります。

人間の学習サイクルは、普通は個人に閉じています。自分の頭の中だけに「良い仕事の進め方」のノウハウがあり、それを日々暗黙的に改善し続けています。

他方、自分が良しとしている仕事の進め方を型化してドキュメントに落とし込み、他の人にもそのフローに従ってもらうこともできます。自分しか踏んでいなかったフローを他人にも踏んでもらうようになると、様々な状況の違いから、問題が噴出します。このとき、フローはすでにドキュメントに明文化されているので、「フローに問題がある場合はドキュメントを修正しよう」ということになります。これこそが、仕事の学びがドキュメントに蓄積されていく状態です。

個人の学びをチームや組織の学びに変えていくことは、不確実性と戦う上で重要なポイントです。まずはドキュメントを共同でメンテナンスする文化を醸成することが、その第一歩であると僕は考えます。

あなたも、ドキュメントを書くところからエンジニアリングを始めてみませんか？