ドキュメントをいい具合に残そうの会

Last updated at 2024-03-05Posted at 2024-02-26

最近、『エンジニアのためのドキュメントライティング』という本を読みました。
非常にためになる内容だったので、本書であがったいくつかのポイントを私なりにまとめてみました。

また、エンジニアにとってのドキュメントは種類が多く、それぞれのニーズとそれに合わせたフォーマットも違うため、 良いドキュメントとは何か？ を一概に述べることは難しいです。
個人的には、「ほぼ知識のない人が読んでも再現できる・解決できる」ということが大事なのではないかと思っています。

そこで、本記事ではドキュメントの範囲を少し絞って、想定される読者をエンジニア寄りに考えて書いています。ご了承ください。

フリクションログをつくる

フリクションログとは、あるユーザー¹の体験を記録するログのことであり、「期待する振る舞い（挙動）」と「実際の振る舞い」を照らし合わせ、そのギャップをフリクション（摩擦/衝突）として記録する、というものです。

フリクションが多ければ、その箇所が 改善ポイント＝ユーザーの「ニーズ」 となり、体験を補助するためにドキュメントを作るきっかけになります。

見出しで全てを説明すること

ドキュメントを読むユーザーの多くは、基本的に流し読みをします。隅から隅まで読むことはしません。
そのため、ドキュメント内のブロックを明確にし、段落を分け、その内容が一目で分かるような見出しをつけておくことで、読みやすいドキュメントになります。

手順を書くこと

個人的に最も大切なポイントは 「着手〜完了」のプロセスを明確にすることです。
そうすることで、似たプロジェクトや障害に取りかかる際、「何をするべきか」に素早くリーチでき、業務の最適化に繋がります。

例えば、環境構築で踏んだ手順、バグ発生の再現手順、原因解明の調査手順など…
どのようなドキュメントでも、手順を明記しておくことは外せないでしょう。

完璧さを求めすぎないこと

本書によれば、ドキュメントを作成するときの最も大きな障害は、書き出すまでの白紙の状態だそうです。

なにはともあれ書いてみる、という気軽さでドキュメントを作成しましょう。箇条書きでも、書きたいところから詳しく書いても、それが順不同でも、最初のドラフトでは無問題です。

ドキュメントオーナーを明確にすること

ドキュメント更新の責務を明確にすることは、良いドキュメントには欠かせない条件です。内容の更新をする担当者をつけることで、ドキュメント内の情報が古くなったまま放置される問題を防ぎます。

ドキュメント作成者が必ずしもドキュメントオーナーとは限りませんが、内容について訊かれたときの対応を考えると、なるべく揃えておいた方がよいかもしれません。

ドキュメントへの導線を考えること

せっかく見やすいドキュメントを作成しても、アクセスしにくい場所に保管されていたらもったいないです。

適切な場所にドキュメントを置くことは、良いドキュメントの重要な条件です。また、メンテナンスの面倒を避けるためにも、ひとつのドキュメントは一箇所に置くようにしましょう。

本書ではリリースノートやREADME、バグ報告レポートのテンプレート、あるいはコードに残しておくコメントの話もあり、エンジニアとして触れるすべてのドキュメントに関するtipがたくさん紹介されていました。

気になった方はぜひお手に取ってみてください📖 おすすめ本です！

本書での「ユーザー」とは、開発者や顧客などにかかわらずサービスに触れるあらゆる人をイメージしていますが、本記事ではより開発者にフォーカスした人物像をイメージしています。 ↩