エンジニアのためのドキュメントライティング - Forkwell Library #19に参加してきた

forkwell.connpass.com

こちらのイベントに参加してきたので、会の様子と感想を書いていこうと思います。

会の概要

以下、イベントページより引用です。

これまで Forkwell のイベントで登壇されたエキスパートの方々は、先達が記した書籍から「気づき」を得て実践し、振り返り、再現性のある「学び」として身に付けていく中で、実績を築いてこられました。

しかし、日々限られた時間の中で知識や情報をアップデートし続けるのはそう簡単ではありません。

Forkwell Library では、著者・訳者・実践者らを登壇者として招き、そんな思いを抱えた開発者の皆さまが「学びのきっかけ」を得られる勉強会を目指します。

今回の第19回目では2023年3月11日発売の『エンジニアのためのドキュメントライティング』（原題：Docs for Developers）を取り上げます。 「ドキュメントを書いておけばよかった」 開発者であれば一度は思ったことがあると思います。 本書は架空のソフトウェア開発チームのストーリーを追いながら、ソフトウェア開発ライフサイクルの各ステップにおいて、ユーザーニーズの理解、開発者に役立つドキュメントの作成、公開、測定、保守に至るまで、開発を最適化するためのドキュメント作成の技術を解説しています。 基調講演では本書の翻訳を担当されたfukabori.fmでも有名なiwashiさんをお招きし、エンジニアがドキュメントの作成・運用に苦しまない様なノウハウをお伺いしていきます。

会の様子

基調講演〜エンジニアのためのドキュメントライティング〜

まずはiwashiさんから基調講演がありました。以下、内容を記載していきます。

発表の前提

発表の前提として、今日のイベントの対象者が「ドキュメントを書いておけばよかった」と思ったことがあるけれど書き方を体系的に学んだことのないエンジニアである旨の説明がありました。

書籍の概要

大まかに分けると、

ドキュメント作成の準備→ドキュメントの作成→ドキュメントの公開と運用、の3つのPartから成り立っているというお話がありました。

併せて、

ユーザーを理解してジャーニーを書く→仮説検証のために実装→リリースして反応を見る

というプロダクト開発の流れと近似しているのでは？という話もありました。*1なお、各章の目次としては以下のようになっているということです。

1章 : 読み手の理解
2章 : ドキュメントの計画
3章 : ドキュメントのドラフト
4章 : ドキュメントの編集
5章 : サンプルコードの組み込み
6章 : ビジュアルコンテンツの追加
7章 : ドキュメントの公開
8章 : フィードバックの収集と組み込み
9章 : ドキュメントの品質測定
10章 : ドキュメントの構成
11章 : ドキュメントの保守と非推奨化

読み手の理解(1章)

本書で一番重要なPartがここだということでした。
ドキュメントを書く上で一番大事なのはユーザーを理解する(誰がユーザーで何を達成したいのか？)ことだというお話で、これができないとビルドトラップの兆候になりかねないということです。

ユーザーを理解するためには、まずは過去に課題を解こうとする際に作られたログやメモをまずは読み込んで仮説を作って、その仮説を基にユーザーと直接話して仮説検証する方法が本書では紹介されているということでした。

また、ここで得た情報はユーザーペルソナやユーザーストーリー、カスタマージャーニーマップとしてまとめておくことも重要だということでした。*2

なお、ここまでの話を聞いたり1章を読むと、顧客へプロダクト提供するときのドキュメント or 開発者向けのAPIの話が対象かと勘違いしがちですが、実際にはほとんどのドキュメントで応用できる考え方なので、そのつもりで読んでほしいということでした。

ドラフトの執筆(3章)

白紙状態から脱出することが一番難度が高いため、まずは手に馴染んでいるツールを使ってドラフトを書き始めることが重要だということでした。
ドラフトを書き始める際には、冒頭で「誰が」「なんのために」読みにくるのかを考えてからタイトルとアウトラインを決めることがポイントで、そこにどんどん肉付けしていくことが推奨されているそうです。

肉付けに使える要素としては、

• 見出し(ドキュメント内の標識として機能する。最も重要な部分を書く)
• 段落(ドキュメントの詳細理解に役立つ。情報量が多いので読むのはしんどい点に注意)
• リスト(要素がざっと読める。順不同が基本だが重要順に並んでいたりアルファベット順に並んでいるとなお良い)
• コールアウト(もしかしたらシステムにやばいことが起きる、みたいなものを色付きで記載)

があるということでした。

ただしユーザーはFパターンでざっくりとドキュメントを読むので、全部読まないといけないドキュメントではなく、ユーザーが流し読みで必要な情報を見つけられるような状態が理想だということです。(最も重要な情報は冒頭で述べる、大きな文章のかたまりを分割する、方法ごとに分割する)

フィードバックの収集(8章)

ドキュメントもフィードバックを収集して必要に応じて直していく必要があるということでした。

フィードバックを集めるためには、

• フィードバックを送れるための経路を用意
• ドキュメントが役に立ったかどうかをクリックする動線を用意して感情を集める
• ロイヤリティが高いユーザーが集まる場で質問を投げかける

といった方法がありますが、ユーザーが多い場合にはフィードバックが集まりすぎる可能性があるため、フィードバックをトリアージしておくことも大切だということです。(k8sのIssue Triage Guidelinesが参考になる)

ドキュメントの品質測定(9章)

ドキュメントの品質定義は、「目的(ユーザーの特定の行動を促進すること+組織のゴールを達成すること)にかなっていること」だと言えるだろうということで、要素としては機能品質と構造品質に分割できるだろうというお話がありました。(ただしこの2つの品質であるなら機能品質の方が圧倒的に重要)

具体的に言うと、機能品質とは、

• アクセシビリティがある
• 目的がある
• 見つけやすい
• 正確
• 完全

であり、構造品質は

• Clear(明確)
• Concise(簡潔)
• Consistent(一貫)

と表現できるということです。

また、ドキュメントのメトリクスとしては、PV数/ユニークユーザー数/直帰率/TTHWなどがあるものの、確認するメトリクスを絞り込むことやメトリクス活用の計画をたてることが重要だということでした。

日本語特有の観点

日本語の作文技術に関する書籍は多く存在しますが、理科系の作文技術や日本語の作文技術、日本語スタイルガイド、ヘルプサイトの作り方、などを読んでおくと良いのではないか？ということでした。

Q&A

以下、Q&Aであった話を一問一答形式かつ常体で記載していきます。

ドキュメント作成の文化や習慣を会社に浸透させるためには？

まずはドキュメントの価値やどれくらいの優先度なのかを話し合うのが重要。優先度が下がりがちな原因としては、ドキュメントを書くスキルがないことや痛い目にあったことがないことが挙げられる。

ドキュメントの保守を褒め称える取り組みの？

kudoカードなどがおすすめ(既存の仕組みとして用意されている部分に乗っかる)

ドキュメント管理ツールのおすすめは？

アトラシアン、Notion、GitHubなどがおすすめ。
特にNotionのリマインド機能で、定期的にドキュメント価値を話すことは重要。

ドキュメントのオーナーは？

書いた人がオーナーになるのがいいと思う。

設計ドキュメントがない状態で開発を引き継いだ場合は何から始めるといいのか？

書きやすいところから書く。ユニットテストがない状態で何から始めるのか？という話と似ている。

運用しやすい運用ドキュメントのツリー構造はどう決める？

書籍にあるドキュメント構成パターンを使う。カードソーティングを活用するのも手。

ドキュメントが増えてきた場合にどこにあるのかを明らかにするためにできる工夫は？

誰か一人担当を決めておくか、検索でどうにかするパターンの2つがあると思う。Flutterをはじめとした優れたドキュメントを確認するのも一つの手だと思う。

キャリアが長いゆえにドキュメントの必要性を感じないシニアエンジニアにどうアプローチするか？

真正面からフィードバックするのが一つの手。

ChatGPTでどこまで対処できるのか？(ChatGPTがドキュメントを書くのを代替する時代が訪れるのではないか？)

まだもう少し時間がかかるのではないか？例えば、日本語特有の修飾語の順序の違いなどを直してもらうのはまだ無理だった。

ドキュメントって書けば書くほど保守性が低くなるし実装との乖離が起きるリスクがあると思うがなにか知見はあるか？

DODに含めてしまうのは一つの手。

WFでドキュメント納品を求められるのだがどうしたらいいか？

ビルドトラップにはまっている。合理的になぜ必要なのかを相手に聞いたほうがいい。しれっとさぼってみるという手もある。

ドキュメントにもLinterはあるか？

textlint, Just Right!(有償)

複数人でドキュメントを書くと内容の粒度や一体性がなくなるのだがどういう対処方法があるか？

フィードバックしてアラインするようにしないと将来的にはスケールせず大変なことになるので、一人で全部直すよりはフィードバックをして直してもらうのがおすすめ。

理科系の作文技術は漫画版でも参考になる？

なった

会全体を通した感想

Q&Aも基調講演もiwashiさんらしく内容が見事に整理されていて、本書の内容の有益性がひしひしとしみる内容でした。

自分自身、ドキュメントを書く機会というのは増えてきているので、本書をぜひ読んで、ドキュメント作成が得意&楽しくなればいいなあと思いました。

*1:ただし、エンジニアのドキュメント技術にフォーカスしているので、ロジカルライティングやパラグラフライティングなど書いてない内容もある。これらの内容が読みたいときは、理科系の作文技術やロジカル・ライティング、考える技術・書く技術あたりを読むのがおすすめ

*2:ただし認知バイアスの一種として知識の呪い(知っていると思っていることを伝えられない)に陥らないように注意。知識の呪いを断ち切るためには、フリクションログを作成して引っかかった体験を書いていくことやユーザーに共感することが有効