Docs for Developers -ドキュメントに悩めるソフトウェアエンジニアへ-

概要

この記事は2021年にApress社から出版された書籍、Docs for Developersの概要をまとめたものです。

https://docsfordevelopers.com/

私自身は社内の技術関連のドキュメントを書くことに関する重要性を感じ、自分なりに実践しつつも、効果的な運用方法や型のようなものを求めていた状態でこの本に出会いました。
本書ではドキュメントに関する計画から実践、リリースから運用まで包括的に実践的な内容が紹介されています。
ドキュメントに悩めるソフトウェアエンジニア、組織にドキュメント文化を導入したい方にもオススメできる一冊ですので、その概要を紹介したいと思います。

著者について

5人の著者による共著です。

5人はTechnical WritingやDeveloper Advocateのロールで働く方たちで、Google・StriipeなどのTech企業や、UKのGovernment Digital Service (GDS)などで活躍されています。

そのためか全体に抽象的な理論としてではなく、実用的・実践可能な内容になっています。
前書きでの「コードそれ自体がドキュメントであるというのは正しいけれど、
14ヶ月前にあなたが書いたコードに障害が起き、その時にドキュメントがTODOだらけだとしたら?」という問いかけから現場感にあふれ、ぐっと引き込まれるものがありました。

各章のサマリー

本全体はCorg.lyという犬の鳴き声を人間の言葉に翻訳してくれるAPIを提供している、という設定の架空の会社を題材に、サービスの初期開発時からドキュメントを整備し公開、運用していく課程をなぞって進行します。

その流れと同期し、ユーザーの理解からドキュメントの計画・作成、メンテナンスまでの内容をカバーする以下11章から成っています。

Chapter 1: Understanding your audience

この章はドキュメントを書く前提として、提供しているサービスのユーザー = ドキュメントの読者を理解しよう、という章です。
ユーザーヒアリングの実施、ペルソナやジャーニーマップの作成などUXの領域に近い活動やアウトプットについて主に触れられています。

Friction Logと呼ばれる自身がサービスを利用している時のひっかかりを記録するためのフォーマットが紹介されています。サービスを有料化する時など特定のシチュエーションにしぼり、その際の体験を番号付きのリスト(1. ○○○ 2. ✗✗✗...)として記録するようなフォーマットです。

Chapter 2: Planning your documentation

ドキュメントの分類として以下のドキュメントタイプが紹介されています。

• Code comments
• READMEs
• Getting started documentation
• Conceptual documentation
• Procedual documentation (手順書)
• Tutorials
• How-to guides
• Reference documentation
  • API reference
  • Glossary (用語集)
  • Troubleshooting documentation
  • Change documentation (リリースノートなど)

↑のドキュメントタイプを利用しなから、以下内容を含むリストを作成して計画を行います。

• タイトル
• ドキュメントタイプ
• 概要

Chapter 3: Drafting documentation

まずドキュメントをドラフトします、まず最初に以下を設定します。

• Audience
• Purpose
• Pattern

さらに箇条書きのレベルでOutlineを作成し、ドラフトに入ります。
ヘッダーやリストなどドラフトを構成する要素や「読者は読み飛ばしながら読むと想定しよう」などのTIPSが書かれています。

Chapter 4: Editing documentation

4つの観点からEditingについて触れられています。

1. Technical accuracy
   1. 技術的な確かさ
2. Completeness
   1. 読者にとって必要な情報が過不足なく記載されているか
3. Structure
   1. タイトルや見出し、また本文全体が一貫性をもって論理的に構成されているか
4. Clarity and brevity
   1. 一文一文を読み、重複や不要な部分の削除を行う

その後レビューのプロセス(セルフレビュー -> ピアレビュー -> テクニカルレビュー)やフィードバックを受ける側、する側の心持ちやTIPSが書かれています。

Chapter 5: Integrating code samples

ドキュメントに埋め込むコードサンプルについてです。

コードサンプルには 1.executable(実行できるもの) 2.explanatory(説明用のもの)の2種類があるとしています。

良いコードサンプルの条件として以下があげられています。
4, 5についてはexecutableなコードサンプルのみに関わります。

1. Explained
   1. コンテキストや説明と共にかかれていいること
2. Concise
   1. 適切な量の情報を提供していること
3. Clear
   1. 利用されている言語の慣例に従っていること
4. Usable (and extensible)
   1. 読者がそのコードをどう利用してよいのかがわかること
5. Trusteorthy
   1. ペースト可能で確実に実行できること

Chapter 6: Adding visual content

スクリーンショットや図の作成など、ドキュメントに埋め込む視覚的コンテンツについて触れられており、
図に関してはパターンや色の一貫性など図の作成の関してのTIPSが書かれています。

Chapter 7: Publishing documentation

• リリースプロセスの作成
  • タイムライン
  • コードのリリースとの協調
  • 最終化、承認プロセス
  • 公開方法を決める
  • ドキュメントの公開・更新をユーザーに伝える

Chapter 8: Gathering and integrating feedback

ドキュメントに対するフィードバックをアンケートなどの方法で受ける方法、
また受けたフィードバックを実際の行動に移す方法、フィードバックをくれたユーザーとのコミュニケーションについて書かれています。

フィードバックを実際の購読に移す方法では報告のトリアージステップとして以下が紹介されていました。

1. 課題が正しいかを検証する
   1. "trust but verify"の精神を持つ
2. その課題は修正可能かを判断する
   1. 既出の問題かを判断 -> 再現可能かの検証 -> 修正範囲の検討
3. 課題に優先順位をつける

Chapter 9: Measuring documentation quality

ドキュメントの品質を評価する方法についての章です。

ドキュメントの品質をFunctional quality(ドキュメントがその目的・ゴールを達成しているか) とStructual quality(文章としての構成)に分けて説明されています。

ドキュメントがゴールを達成しているかを測るための、定量的な測定・分析方法についても触れられています。

Chapter 10: Organizing documentation

いわゆるサイトマップやそのナビゲーションなど、ドキュメントの構成の仕方についての章です。

Chapter 11: Maintaining and deprecating documentation

コードと足並みをそろえてドキュメントもメンテナンスが求められる、とされています。
そのための実践方法としてドキュメントのオーナーを設定、リンクチェッカーを運用するなどのプラクティスが紹介されています。

まとめ

以下2点が自分自身が本書、Docs for Developersが特に素晴らしいと感じた点です。

すぐに実践できるノウハウが得られる

全編的に実践的な内容ですが、特にPlanning your documentationの章にあるドキュメントタイプ、またそれを活用した計画の立て方の部分は取り入れやすいと感じます。

ドキュメントにもソフトウェア開発同様、プロセスが必要であることに気づける

ドキュメント全体の計画をたてる、レビューやリリースのプロセスを整える、ゴールを設定して定量的な計測をする、継続的なメンテナンスの体制を整える、というのはソフトウェア開発であれば一般的な内容ですが、
ドキュメントに関してはそれが必要である、ということ自体この本を読んで初めて気付かされました。

逆に言えばソフトウェアと同じようにメンテナンスしていけば良いと考えれば、ドキュメントを計画・作成・運用するための方針を考える助けになりそうです。