ドキュメンタリアンとは、役職に関係なく、ソフトウェア業界でドキュメントとコミュニケーションに関心を持つ人のことです。
はじめに
これは主に『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』の書評です。私はSreakeにてSREという役職についています。SREはサービス概要、アーキテクチャの解説や図、各種構成図、各種手順書、ポストモーテム、ポリシー、SLA(SLO) … その他の様々な場面でドキュメントを書く必要があります。しかし、ドキュメントは価値が見えにくく時間と労力がかかり品質担保の面で重要度がとても高いのにその場での価値が見えにくいので浸透しにくいです。そのため、エンジニアとしてモチベーションが保ちづらいです。2021年 State of DevOps 2021 にもドキュメントに関する言及があり今後、DevOps やSREの領域でドキュメントの重要性が高まるのは言わずもがなです。
書籍情報
『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』 ジャレッド・バーティ (著), ザッカリー・サラ・コーライセン (著), ジェン・ランボーン (著), デービッド・ヌーニェス (著), ハイディ・ウォーターハウス (著), 岩瀬義昌 (翻訳)
本書は『Docs for Developers』の翻訳本でもあります。
日本能率協会マネジメントセンターのサイトから引用した本書の概要です。
「ドキュメントを書いておけばよかった」開発者であれば一度は思ったことがあるかもしれません。ドキュメントは開発側の生産性とユーザーの利便性を高めるものです。さらに言うと、ドキュメントがなければ、ユーザーに使われる機会が確実に減ります。開発者がいかにすばらしいプロダクトを作ろうが、ドキュメントの欠如がその価値を奪うのです。本書は経験に長けた執筆者たちがドキュメントを作成する方法をゼロから説明するフィールドガイドです。架空のソフトウェア開発チームのストーリーを追いながら、ソフトウェア開発ライフサイクルの各ステップにおいて、ユーザーニーズの理解、開発者に役立つドキュメントの作成、公開、測定、保守に至るまで、開発を最適化するためのドキュメント作成の技術を解説しています。これまで学ぶ機会のなかったREADME、APIリファレンス、チュートリアル、コンセプトドキュメント、リリースノートなど、さまざまな種類のドキュメントの書き方について学ぶことができる一冊です。ドキュメントを作成している現場のエンジニアやテクニカルライター、プロダクトマネジャーの方に最適の内容です。
翻訳の方と著者の方のPodCast も公開されているのでこちらもオススメです。
イベントもやられてました。エンジニアのためのドキュメントライティング - Forkwell Library #19
「ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング」の目次
PARTごとに別れていて「PART I ドキュメント作成の準備」→「PARTⅡ ドキュメントの作成」→「PARTⅢ ドキュメントの公開と運用」に分かれている。それぞれのフェーズで必要な知識や心構えが書いてある。各章とも端的にまとまっているのでオススメです。また、書籍を読んだ後に各種公式ドキュメントを読み込んでよくできているなぁって思うのは体験としてはよいのでオススメです。
PART I ドキュメント作成の準備 CHAPTER 1 読み手の理解 CHAPTER 2 ドキュメントの計画 PARTⅡ ドキュメントの作成 CHAPTER 3 ドキュメントのドラフト CHAPTER 4 ドキュメントの編集 CHAPTER 5 サンプルコードの組み込み CHAPTER 6 ビジュアルコンテンツの追加 PARTⅢ ドキュメントの公開と運用 CHAPTER 7 ドキュメントの公開 CHAPTER 8 フィードバックの収集と組み込み CHAPTER 9 ドキュメントの品質測定 CHAPTER 10 ドキュメントの構成 CHAPTER 11 ドキュメントの保守と非推奨化
目的があるドキュメントを書こうと思わせてくれる本
『コードを読めば分かるから、ドキュメントは今は書かなくていいかな？』って言った人はその後もほとんど、ドキュメントを書かない。ちなみにこういう人はコメントもあまり書いてくれない。エンジニアが新たにシステムを理解したいときはいくつかの場面がある。「エンジニアが新たにシステム開発/運用に参加したとき」「エンジニアが自分の担当以外の構成要素や機能を理解したい時」、その他、様々な場面etc…。システムで利用している技術スタックに十分な知見があったとしても、意外に開発を開始までには手間と時間がかかる。
新しく参画したエンジニアが動いているソースコード以外に何もない状態ではシステムへの理解をする時に本当に苦戦する。場合によっては挫けてしまう。ドキュメントがあったとしてもポエムやコラムみたいにお気持ちがたくさん書かれていてもシステムの理解の助けにならなければ価値が薄い。だから、エンジニアは優れたドキュメントを継続的に存在させ続ける必要がある。ドキュメントはテストと同じくソフトウェアエンジニアリングという領域の基礎をなすものだと確信していますが良いドキュメントを書くことを意識することはよくドキュメントを読む時に書いている人の気持ちを考えたりなどいい習慣が身につきより価値のあるドキュメントが書けると思います。
よいドキュメントとはどのようなものか
PARTⅢ ドキュメントの公開と運用では良いドキュメントについて以下のような定義をSREの探求の19章 ドキュメント作成業務の改善：エンジニアリングワークフローへのドキュメントの統合 から引用している。『良いドキュメントとはドキュメントの品質が高いこと、ドキュメントが目的にかなっていること』もう少し品質について分類すると構造品質と機能品質にわけられる。構造品質と機能品質にはそれぞれ多くの要素が含まれますが今回は割愛します。CHAPTER 10 ドキュメントの構成 にはアクセスしやすいようにドキュメント全体をどうデザインするかについて書いてあり社内でも今後取り組んでいきたい部分が記載されていました。社内のドキュメントを整備する時に情報アーキテクチャ ―見つけやすく理解しやすい情報設計を読んでこれもとても参考になったのでオススメです。また、CHAPTER 11 ドキュメントの保守と非推奨化にはドキュメントを容赦なく刈り込む重要性について記載されています。ここがブログなどとは大きく違う点だと思う。そのドキュメントの機能構造が発揮できなくなったら削除したり非推奨にするのが大事です。陳腐化された、ドキュメントは削除する削除できない場合はアーカイブしたり、ステータスとして「廃止予定(Deprecated)」を付与することは本当に大切です。
機能品質
ドキュメントの内容がその目的を達成するかどうかを評価します。これには、情報の正確さ、完全性、信頼性、時宜性、明瞭性、関連性が含まれます。機能品質が高いドキュメントは、読者に有用な情報を提供し、目的に沿った結果を生み出すことができます。
障害対応手順書を例に上げると
- 全てのアラートに対して手順が用意されているか
- 誰でも作業ができるか(1次受けができるか)
- 定期的なアップデートがされているのか
- 必要な人が必要なときにすぐアクセスできるか
などなどドキュメントがあることによってビジネスバリューが発揮できているか。これは読む人それぞれでとても変わりやすいと思うし評価もしずらいです。機能品質の評価の施策についても本書もしくはSREの探求19章には記載されているのでぜひ読んで下さい。
構造品質
ドキュメントがうまく書かれているか、うまく構成されているか？ドキュメントの形式、構成、レイアウト、デザイン、文法、綴りなどの側面を評価します。これらの要素が適切に整理され、適切に機能すると、読者は情報を簡単に理解し、必要な情報を効率的に見つけることができます。
評価しやすい品質
- textlintかけて通過しているとか
- 構成テンプレートに沿っているとか
大切なのは総合品質だが機能品質を優先せよ
- 総合品質 = 機能品質+構造品質
- 結局は「推測するな、計測せよ」なので本書を読んで計測方法について学んでくれ
- 構造品質は評価しやすい一方、評価指標をこれだけにしてしまうと本質を見失ってしまう
- 当然どちらも高いことが望ましいが、機能品質は常に構造品質よりも重視されるようにする。
総合品質を守りたいんじゃぁああああ
PART I ドキュメント作成の準備にしてもPARTⅡ ドキュメントの作成にしても結局は総合品質の高いドキュメントを素早く作成して、特定の期間中に品質を保ち、必要に応じて廃棄していくための取り組みなのかと思いました。どのような人が読むのか想定して、ドキュメントの目的を決めてドキュメントを書く。ドキュメントを書く時に白紙からスタートするのは非常に辛いので目的が達成されやすいテンプレートを用意する。自動生成を用いる、理解を促すために図解を利用する。様々な施策を行うことで良いドキュメントを書くことに取り組む学びが多い本書です。良い技術ドキュメントの書き方がわかると良いドキュメントが書きたくなるものですよね。みんなにドキュメントを書いてほしいのでとにかく、読んでほしいとおもいました。
ドキュメントに関する入門書は他の分野ではあるがソフトウェアを運用/開発するための技術ドキュメントの為に読むべき本って無いよね、という話になりがちだけど、本書はまさにそんな人たちが読みたい1冊だと思います。
知識の呪いもしくは祝福
人間は他人が自分と同じ知識をもっていると思い込んでしまいます。登壇資料などでも同じですがそれらを作った直後に読み返してみても全てが既知すぎて本当にこのドキュメントや資料には価値があるのか？ と自分に問い直すことがあります。その時に読み手を意識して読み手をどう結論やゴールに導きたいか事前に考えておくことは非常に助けになります。世界で一番やさしい 資料作りの教科書という書籍があってエンジニアだけに向けた書籍ではないのですが読み手の設定と目的と価値のあるドキュメントやコミュニケーションをどのように作っていくか本当にわかりやすくまとまっているのでオススメです。あなたが悩んだことはいずれ誰かも悩むことになります。特にブログは技術ドキュメントとは性質が違うものなので気にせず書いていきましょう。
自動化について話したい
ドキュメントの中でも機械的に作業が自動化できる場合があります。相対的にトイルっぽくなる作業になるので自動化できるものに関してはCIなどで自動化せずとも存在を知ってたりとか自動化できる事実を知っていれば今後の糧にしてほしいです。個人的にはテンプレートの作成を先にやった方が効果があると思います。あくまで個人的には。issue templatesを用意しましょう。
- terraform-docs
- Terraform module を利用する際にパラメーターやアウトプットなどの機械的な情報の説明を書くのは非常に手間です。それらの機械的な情報をまとめてくれるのがterraform-docs になります。
- https://github.com/k1LoW/tbls
- DBの必要な情報をCIフレンドリーに出してくれる最高のツールなので案件でDBを使っていれば積極的に採用していきたいと思ってます。
- データベースのドキュメント作成を現場の開発エンジニアもやりたくない人が多いはず
- protoc-gen-doc
- Protocol Buffers 用のドキュメント生成用のプラグイン
- htmltest
- htmltestを使えば生成されたHTML内のリンク切れを発見できます。
- textlint
- Prettier
あとがき
2023年3月15日では、GPT-4 が登場し、さまざまな意見が飛び交っています。私自身も仕事でChatGPTを利用しているため、その特徴はぼちぼち理解しています。ChatGPTが得意なのは、過去のデータを基に『ドキュメントの作成』をすることです。『ドキュメント作成の準備』と『ドキュメントの公開と運用』は依然として人間が担当していくと思います。
GPT-4などの技術を適切に活用しつつ、ドキュメンテーションにおける人間の価値を維持するためには、バランスの取れた使用、クリティカルシンキングの維持、継続的な学習、コミュニケーションスキルの重視、チームワークと協力、そして創造性とイノベーションを大切にすることが重要です。何より重要なのは自分の頭でちゃんと考えることです。ChatGPTを利用したドキュメント化生成ツールが出てくるとは思うのでその時には『ドキュメント作成の準備』と『ドキュメントの公開と運用』がより大事になってくると思いました。
