【エンジニアコラム】ドキュメント作成において1番重要なポイント

2024年4月19日2025年1月29日

はじめに

エンジニアはたくさんドキュメントを作る機会があります。ウォーターフォールでもアジャイルでもほとんどのフェーズで何かしらドキュメントを作っています。

ただ、全国のエンジニアが長い時間をかけて頑張って書いているドキュメントですが、ある一つのポイントが守れていないだけでまったく意味のないものになってしまいます。逆にその一つのポイントを守れるだけで素晴らしいドキュメントになります。

今回はその絶対に守るべきポイントと、なぜそれが重要なのかについてお話しします。

絶対に守るべきポイント

絶対に守るべきポイント、それは「使われるドキュメントであること」です。

どれだけ細かく書かれていても、どれだけ分かりやすく書かれていても、後の工程で使われないドキュメントでは存在する意味がありません。

あなたはそのドキュメントが次の工程でどのように利用されるのか具体的にイメージしてから書き始めているでしょうか？どんな知識を持った人が、どんなタイミングで、何を目的としてそのドキュメントを利用するのか。ここまで具体的にイメージしてから書き始めないと使われるドキュメントにはなりえません。

エンジニアのタスクはチケットごとに取り組むことが多いかと思います。チケット別での業務はタスクが明確になりそのタイミングで何をやれば良いか分かりやすくなるメリットはありますが、取り掛かっているタスクだけに目が行きがちになるというデメリットもあります。

その結果とりあえずドキュメントとして問題が無いように漠然とそれっぽい情報をまとめてしまうことが多発します。そして次の工程のことを考えられていない悪いドキュメントが大量に出来てしまうのです。

エンジニアの業務は長期戦です。すべてのタスクは全体の中のほんの一部でしかありません。しかしそのほんの一部の積み重ねが最終的なアウトプットになります。つまりすべてのタスクはつながっているのです。全体を構成するとても重要な部分としてタスクがあるのです。

ドキュメント作成を全体の中の重要な一部分とするためには、後の工程を具体的にイメージして「使われるドキュメント」を意識する必要があります。

メリット

「使われるドキュメント」にする難易度は高いです。なぜなら後の工程を具体的にイメージできる知識や想像力が必要だからです。

ただしこの力は鍛えることが出来ます。

毎回ドキュメントを作成するときに次の工程をできる限り具体的にイメージすることで、テストと答え合わせが出来ます。イメージが正しかったのか否かは後の工程に進んだとき、そのドキュメントがちゃんと使われたかで判断ができます。そしてその判断結果を次のドキュメント作成時のイメージに活かせます。

しかしイメージをしないで作成したドキュメントを利用したときには、イメージできていなかった部分が明確にならずに単純に情報が不足していたと漠然と思って終わりです。それではイメージ力の向上にはつながりません。

次の工程を具体的にイメージできる能力はドキュメント作成だけでなくあらゆる業務でも有用です。そんな力を身に着けられることがとても大きなメリットになります。

また「使われるドキュメントにすること」にはもう一つ大きなメリットがあります。それはドキュメント作成に必要な時間を減らせるということです。

後の工程のことをイメージできると書くべき内容の絞り込みが可能です。変な装飾のいるいらないも簡単に判別が出来ます。

その結果、漠然と良いドキュメントを目指して作られたドキュメントよりも、必要なことだけが詰められた良いドキュメントが出来上がります。またレビューでの指摘もおそらく少ないでしょう。その結果指摘対応の時間も減ります。

まとめ

圧倒的に質が高いドキュメントを最短の時間で作るために意識するべきポイントが「使われるドキュメントか」です。このポイントを意識して書かれたドキュメントか否かは数行読んだだけで判別できます。

最後に簡単にこのポイントを守る方法を伝授します。それはドキュメントの内容として「どの工程で」「どんなスキルを持った人が」「何のために利用するのか」の3項目を明記することです。どんなドキュメントを書くときにもこの項目を最初に埋めた上で始めるだけでドキュメントの質が数段上がります。

ぜひこのポイントを頭に入れたうえでドキュメント作成をしてください。いつかあなたが書いたドキュメントを私が使うときに喜びます。