良いドキュメントの書き方

Author:

2023-10-06

はじめに

こんにちは。hatakoya です。
システム開発においてドキュメントは大切で、適切に書くことで情報共有の効率化が図れたり、日々の業務やトラブルシューティングにおいても効率的に業務を行う手助けとなります。

今回はエンジニアのドキュメンテーションについて私が普段意識すると良いと感じていることを書きました。

ドキュメントといっても議事録や README、コミットメッセージ、Wiki でまとめたシステムの仕様など色々あると思いますが、ここでは主に継続的なメンテナンスが必要となるドキュメントについて触れていきます。

チーム内のエンジニアや、PM、または他のチームのエンジニアであったりと、ドキュメントの対象読者は色々考えられます。また、読者ごとに必要としている情報は異なります。

対象読者の意識が甘いと、必要な情報が不足したり、逆に情報が多すぎて知りたい情報を探しにくくなってしまいます。

そのドキュメントが誰向けなのかを意識し、情報が複雑になってきた場合は詳細な内容など一部の人が知っていれば良い情報については場所をわけるなどして必要な情報を適切に伝えられるようにすることが大切です。

また、書いたあとに一度客観的にセルフレビューしてみて、想定する読者に適切に情報を届けられるかを確認することも有効だと思います。

以下で、わかりやすく書くための Tips をいくつかご紹介します。

必要な情報を探している人はドキュメントを上から細かく読むのではなく知りたいキーワードで検索して特定の情報だけを手早く確認したいかもしれません。
また、エンジニアがソースコードを変更した際に更新すべきドキュメントを探すこともあると思います。

ソースコードであれば IDE の機能を介して影響範囲の発見をサポートしてくれますが、文章化しているドキュメントについては人の手で探さなければならないことも多いと思います。
そういった意味でも検索性を意識した書き方が大切だと考えています。

図や表を使うことで視覚的に表現でき素早く理解できるようになります。
文章だけで伝わりにくいと感じたら、画像などを利用して複雑な内容をわかりやすい見た目でまとめると良いです。

コーディングにおいても実装の背景をコメントで補足することがありますが、ドキュメントにおいてもこれを書くことで読者の理解をスムーズにする助けとなります。
例えばシステムの仕様について説明するような場合でも、推測しにくいなにかしら特殊な背景があるのであればそれは書いておくべきです。

継続的にメンテナンスするものは保守性を維持することも重要です。
複雑なソースコードがメンテナンスしにくくなるのと同じく、ドキュメントについても正しく正規化しながらメンテナンスすることでより良いものになります。

ドキュメントの中には常に最新情報にしておくべきものと、そうではないものがあると思います。
より多くの人に読まれるものは頻繁な更新が求められ、逆に限定的な人しか参照しないものについてはそこまで厳密ではなくても良いかもしれません。

理想的にはすべての情報を常に管理できれば良いですが、日々の業務で時間的な制約もあるなか、すべてを常にリアルタイムで完璧に更新するのは難しいことが多いと思います。

そのような中で効率的に有効な情報に更新しつづけるために、必要な更新頻度も意識してどの程度詳細にメンテナンスしていくかを切り分けると良いです。

後回しにしがちなこともあると思いますが、気づいたらすぐに書くのも重要です。
あとで一気にまとめようしても腰が重くなってしまうので、小さな更新だけで済むうちに書くほうが気持ち的にも楽になります。

当然ですが、更新がされないまま放置してしまうと徐々に陳腐化し信頼性がなくなってしまいます。
せっかく書いてもそれではもったいないので、定期的に見直して更新しましょう。

そのためだけに時間をとって見直すのは難しくても、プルリクエストを作るときやコードレビューのタイミングなど、チェックポイントで確認するというのも良いと思います。

この記事ではより良いドキュメントを書くための Tips を紹介しました。

ドキュメンテーションは難しいですが、書いていくうちに慣れていくこともあるので、とにかく色々書いてみるのが良いと思っています。この記事がお役に立てれば幸いです。

また、弊社 Belong は一緒に働くエンジニアを募集しています。
興味がある方は https://entrancebook.belonginc.dev/ をご覧ください。