ドキュメント文化が何となく良いのはわかっているけどドキュメントを書き始める前にその目的や背景を意識する方が良いのかもしれない

今回のお話

ドキュメントを書いていますか？
webサービスやプロダクトに携わっているとクライアントワークであろうと事業会社であろうと必然的に避けられないのがドキュメントです。

それは、仕様書や設計書など機能に関連するものからメルマガのテンプレートなどサービス運用に関わるものであったりします。

その際に、意識すべきことは「誰が読んでも理解可能かどうか」ということです。すなわち、以下に留意する必要があると思っています。

①簡潔であるかどうか
②正確であるかどうか
③読みやすさはあるのか

今回は、ドキュメントの書き方について考えていきましょう。

限りなく正しさを担保するために細々と詳細なところまで書くドキュメントが必ずしも正解ではないのかもしれない

あえて長いチャプタータイトルにしてみました。
最近のライトノベルは（最近ではないのかもしれませんが）タイトルが長いものが多いですよね。

振り返ると「俺の妹がこんなに可愛いわけがない」や直近テレビアニメでやっていた「痛いのは嫌なので防御力に極振りしたいと思います。」（通称：防振り）などなどありました。

「星を継ぐもの」や「インザミソスープ」など名詞でバシッと短く決めるというのは最近はあまり見かけられませんね。

話を戻すと、ドキュメントを書く上で必ずしも長く書く必要はないかなと思います。先に述べたように、簡潔さ、正確さ、可読性のトレードオフを意識する必要があります。

大前提として「誰が読んでも同じ意味にしか伝わらない」ということがあります。
例えば、「スマホ」と書くと人によってiPhoneであるかもしれないし、AndroidOSのものかもしれません。ただ、意味は通じます。
わざわざApple社製のiOS搭載の携帯情報端末と正確に書く必要はありませんよね。

この「誰が読んでも同じ意味にしか伝わらない」というのも詳細に紐解いてみると、「（そのドキュメントにアクセスできて読む必要のある）誰が（ドキュメントの形式（md,txt,ppt,csv,etc,..)に最適化されたツールを用いて）読んでも（ドキュメントが担保している条件や環境に応じた）同じ意味にしか伝わらない」ということです。

限りなく詳細を詰め込んで正しさばかりを追い求めるドキュメントが正しいわけではなく、どんな読み手にも同じ意味で解釈されるという前提のもと簡潔さや可読性を意識するのが「良い」ドキュメントであると考えています。

ドキュメント文化は属人性の排除につながるかもしれないが、結局のところ目的のないまま心の赴くままに書いてもそれは意味を為さないのかもしれない

ドキュメントを書くにあたっての「目的」とは何でしょうか。
先ほどまで書いた簡潔に正確に伝わるように書くというようなことは、あくまで「お作法」の話かと思います。

それは、テンプレートを用意するやGithubに代表されるバージョン管理でレビューを通すことなどテクニカルな話も含まれます。

ここから書くのは、ドキュメントを書く上での「姿勢」です。
それは「目的のないドキュメントは書かない」ということです。

例えば、アマゾンの会議用の資料はワードで箇条書きはNGという話があるそうです。真偽のほどはさておき、テクニカルにいくとワードよりマークダウンの方が可読性は高いと思ってしまいますよね。校正などレビューや共有においても面倒だったりと管理コストもかかりそうです。

ただよく考えると箇条書きとは言うなればzipファイルのようなもので圧縮された行間を読み手が解凍（＝論理を紐解く）する必要がありますよね。

そういったことをすることなくロジカルに経緯や背景も包み隠さず意思決定の漏れやミスがないようにというような目的のもと「箇条書きをNG」におそらくしているのだと思います。

すなわち、ドキュメントの形式から書き方、管理方法やレビューのありなしなどはすべて目的によって規定されるということです。

組織のオープンさや属人性の排除といったことを考えてもその結果をもたらす目的や意味を考えず、ただ単にドキュメント文化をつくるという手に走ってしまうと、それは我々が最も忌み嫌う「目的と手段の混合」ということに繋がりかねませんよね。

目的や意味というものを据えてからドキュメントに取りかかりたいところです。もちろん既存のドキュメントに関しても「契約で決まっていているので」や「部長さんがそれだと読めないから」というようなことを鵜呑みにして書かずに改めて目的や意味から落とし込むといいのかもしれません。

最後に

どんな職種でもやはりドキュメントを書く目的から書く力まで理解したり、身に付ける必要があると思っています。
エンジニア においてもコードを書く上で誰でも理解可能な変数名を書いたり、インデントなどを含めた可読性を意識しますよね。

優れたエンジニア が「良い」コードを一定量以上「読む」ことで「書ける」ようになっている（それだけではないが）ように、具体性の高いロジカルさや抽象度の高い思想や哲学が含まれた書籍などに目を通すのも一つの手かもしれません。

何もテクニカルなことは一切書いていませんが、テクニックを使いこなすための下地としての「考え方」について書いたつもりです。
言わなくても（ある程度）伝わるのが日本人の美徳ですが、伝えることは正しく伝えられるよう（伝わるよう）に、書き手も読み手もレベルアップしていく必要がありますね。

それでは、また。