エンジニアのためのドキュメントライティング

「ドキュメントを書いておけばよかった」

開発者であれば一度は思ったことがあるかもしれません。

ドキュメントは開発側の生産性とユーザーの利便性を高めるものです。
さらに言うと、ドキュメントがなければ、ユーザーに使われる機会が確実に減ります。
開発者がいかにすばらしいプロダクトを作ろうが、ドキュメントの欠如がその価値を奪うのです。

本書は経験に長けた執筆者たちがドキュメントを作成する方法をゼロから説明するフィールドガイドです。
架空のソフトウェア開発チームのストーリーを追いながら、ソフトウェア開発ライフサイクルの各ステップにおいて、ユーザーニーズの理解、開発者に役立つドキュメントの作成、公開、測定、保守に至るまで、開発を最適化するためのドキュメント作成の技術を解説しています。
これまで学ぶ機会のなかった README、API リファレンス、チュートリアル、コンセプトドキュメント、リリースノートなど、さまざまな種類のドキュメントの書き方について学ぶことができる一冊です。

ドキュメントを作成している現場のエンジニアやテクニカルライター、プロダクトマネジャーの方に最適の内容です。
PART I ドキュメント作成の準備
CHAPTER 1 読み手の理解
CHAPTER 2 ドキュメントの計画

PART2 ドキュメントの作成
CHAPTER 3 ドキュメントのドラフト
CHAPTER 4 ドキュメントの編集
CHAPTER 5 サンプルコードの組み込み
CHAPTER 6 ビジュアルコンテンツの追加

PART3 ドキュメントの公開と運用
CHAPTER 7 ドキュメントの公開
CHAPTER 8 フィードバックの収集と組み込み
CHAPTER 9 ドキュメントの品質測定
CHAPTER 10 ドキュメントの構成
CHAPTER 11 ドキュメントの保守と非推奨化

README や API リファレンス、チュートリアル、リリースノートといった開発者向けドキュメントを、読み手の理解から計画、執筆、公開、品質の測定、保守まで、ソフトウェア開発の流れに沿って作る方法を解説した実践書です。『エンジニアのためのドキュメントライティング』は、原書 Docs for Developers の日本語版で、ジャレッド・バーディ (Jared Bhatti)、ザッカリー・サラ・コーライセン、ジェン・ランボーン、デービッド・ヌーニェス、ハイディ・ウォーターハウスの 5 名が著し、岩瀬 義昌 が訳して、日本能率協会マネジメントセンターから 2023 年 3 月 11 日に刊行されました。副題は「ユーザーの問題解決とプロダクトの成功を導く」です。

3 部 11 章の構成、準備から作成、公開と運用へ

目次は 3 部に分かれます。PART I「ドキュメント作成の準備」は CHAPTER 1「読み手の理解」と CHAPTER 2「ドキュメントの計画」、PART II「ドキュメントの作成」は CHAPTER 3「ドキュメントのドラフト」から CHAPTER 6「ビジュアルコンテンツの追加」まで、間に「ドキュメントの編集」と「サンプルコードの組み込み」を挟みます。PART III「ドキュメントの公開と運用」は CHAPTER 7「ドキュメントの公開」、CHAPTER 8「フィードバックの収集と組み込み」、CHAPTER 9「ドキュメントの品質測定」、CHAPTER 10「ドキュメントの構成」、CHAPTER 11「ドキュメントの保守と非推奨化」です。版元の紹介によれば、全体は架空のソフトウェア開発チームのストーリーを追う形で進み、開発ライフサイクルの各段階でどのドキュメントをどう作るかを示すフィールドガイドとして書かれています。文章を書く手前の準備に 1 部を充て、書き上げたあとの運用にも 1 部を充てている配分から、文章術だけでなくドキュメントを継続して育てる工程全体を対象にした本と読めます。

読み手の理解から始めるドキュメント設計

テクニカルライティング で最初に問われるのは、文体より先に、誰が何をしようとしてその文書を開くのかという点です。同じ機能の説明でも、初めて導入する人にはチュートリアル、仕様を引きたい人にはリファレンス、仕組みを理解したい人にはコンセプトドキュメントが合い、一つの文書に全部を詰め込むとどの読み手にも使いにくくなります。本書が CHAPTER 1 を読み手の理解に、CHAPTER 2 を計画に充て、ドラフトをその後に置いているのはこの順序を反映した並びと読めます。サンプルコードとビジュアルコンテンツにそれぞれ独立した章がある点も開発者向けドキュメントらしいところで、API ドキュメント では、文章の説明より動くコード例のほうが読み手の疑問に直接答える場面が多くあります。

公開後の測定と保守、非推奨化まで扱う後半

開発者向けドキュメントの難しさは、書き上げた瞬間から製品とずれ始めることです。機能が変わればリファレンスは古くなり、手順が変わればチュートリアルは動かなくなります。PART III は、公開の手順に続けて、読み手からのフィードバックの集め方と反映、品質の測定、ドキュメント群が増えたあとの構成、保守と非推奨化を扱います。品質を測って改善につなげる章や、役目を終えたドキュメントの非推奨化を扱う章のように、書き終えたあとの仕事を独立した章として扱っている点が本書の特徴です。刊行時の著者紹介によれば、著者陣は Google のクラウドドキュメントチームの共同創設や、Stripe、Linux Foundation、Monzo 銀行、英国の Government Digital Service などでのドキュメント業務に携わってきた顔ぶれで、組織でドキュメントを運用する立場からの視点が後半の章立てにも表れていると読めます。

現場のエンジニアとテクニカルライターに向く理由、合わない目的

版元が対象として挙げるのは、ドキュメントを作成している現場のエンジニアやテクニカルライター、プロダクトマネジャーです。自分のチームのプロダクトに README しかない、あるいはドキュメントはあるのに問い合わせが減らないという状況で、どの種類の文書をどの順で整え、公開後にどう手入れするかの手順を得たい人に合います。一方で、日本語の文法や句読点の打ち方、言い回しの磨き方を中心に学びたい場合は、日本語の文章技術を主題にした本のほうが目的に近いはずです。本書が扱うのは、文章の一文一文よりも、ドキュメントを計画し、作り、運用する仕組みの側です。

チームのドキュメントを場当たり的な追記から、読み手に合わせて計画し測定しながら育てる仕組みへ切り替えたい人にとって、本書はその道筋を開発の流れに沿って一通り示してくれる一冊です。最初の 2 章で読み手と計画の考え方を押さえるだけでも、次に書く README の組み立てを見直すきっかけになります。