yamarkz
Published on

ドキュメントで何を書くのか

尊敬する同僚の素晴らしい記事に触発されて、イキったツイートをしたら少し反響がありました。

言いたいことは140文字に収まっているのですが、じゃあ具体的にお前は何を書くの??? という疑問が残ると思い、自身の振る舞いまで示せた方が本物っぽいなと思ったので普段どういった内容のドキュメントを書くのかを紹介します。フェイク野郎になるな。

ドキュメントは良いと知っているけど、具体的に何を書くのかわからない...という方の参考になれば嬉しいです。

仕様書

image1

(最初に書いたドキュメントの抜粋 ゴールを定義していた)

仕様書では機能要件や制約、論点などを仕様書に書き出して周りに相談し、論点に答えを出します。

今の組織に属した時に、最初に書いたのは仕様書でした。当時はオンボーディングなどもなく、信頼貯金が0の状態から自分の成果を作らなければならず、まずは周りに自分の仕事を進め方を知ってもらい、働きやすくするためにも仕様書を書くという行為をしてました。

仕様書に何を書くのかは組織によって様々ですが、個人的にはゴールと制約、要件、論点、概念図、考慮などが書かれていれば良いのではないかと思っています。

提案

image2
image3

(提案する内容のドキュメント)

提案は最終的に意思決定に繋げるためのもので、意思決定に必要な検討材料となる情報、提案側の目線で推したい内容を書きます。

例では先にマイルストンを定義し、そこに必要な具体のイシューを列挙しています。 Issueには Must haveといったラベル付もされており、どれに注力したいのかがわかります。

この材料が揃った中で行いたい議論は、何を優先的に解いていくか?解く順序は正しいか?です。

提案先はマネジメントレベルの人で、マネジメントの目線で達成したいことを引き出す、トップの意思を問うための材料になります。想定される反応は、良い、悪い、足りない、追加したい、調整したい、方向を変えたいなど。反応とそれに対する返しを想定して作ると話が前に進みやすくなります。

提案ドキュメントの代替手段として、提案プレゼンがありますが、社内という文脈の解像度が高い組織内ではプレゼンよりもドキュメントの方が優れた手段でしょう。

方針

image4

(どういう状態を目指すのかを示す方針)

方針は明快さが重要で、迷いを減らし、進むべき方向性がわかる書き方にするのがポイントです。

例は開発ドキュメントですが、開発に限らず、何にでも応用できると思います。

ガイド

image5

(特定の問題を解決するためにあるガイド)

具体的で迷いが少ない表現を選びます。初見の人が見ても問題を解けるかどうか、解く手助けになるかが大事です。

Todo

image6

(Todoのリスト)

単純にやること書き出しています。

ストックされるように管理方法を工夫している人も見かけます。

1on1 (相談)

image7

(1on1の前に話したいことを列挙する)

不器用なので、1on1もメモ書きをしてたりします。話したいことを書き出しておくと話がブレない、共有したいことを誤解なく伝えられるのが良いところです。

具体の中身は明かせませんが、大体は顕在化した問題の深掘りを意識して、箇条書きを階層化した内容を書いていたりします。もちろん、何も準備せずに臨む時もあります。

メモ (気づき)

image11

(気づいたことを列挙する)

気づいたことをただ書き出して使っています。

フォーマットなどは特に気にしません。気づいた事実が書いてあることが何よりも重要です。

こういった気づきのメモから方針や対応ガイドなどが作られたりします。

発明は気づきから。

メモ (検討)

image8

(考えていることを整理しながら書く)

思考過程を書きます。メモ自体を誰かに共有しながら、議論が生まれる状態を作るたたき台になるものです。

メモ (調査)

image9

(目的を達成するために調査した内容を書く)

特定の目的を達成するために一時的な情報の置き場。

例では結論を書いていますが、必ずしも結論を出さなければいけない制約はありません。 と、思っている。

(余談)ドキュメントはみなが書けなければいけないのか?

Noです。ドキュメントは凡人がまともに戦うための武器です。そんなものがなくても十分戦えるという人は世の中にたくさんいます。

自分は仕事が死ぬほどできない頃にドキュメンテーションに出会い、なんとかやれるレベルにまでなってきました。凡人が何かを突破したい時のリーサル・ウェポンになるかもしれません。

SHARES