3月17日、「エンジニアのためのドキュメントライティング - Forkwell Library #19」に参加しました。
当日のYouTube Liveアーカイブは以下に公開されています。
エンジニアのためのドキュメントライティング
スピーカーは「ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング」の翻訳者である岩瀬 義昌@iwashi86さん。
『エンジニアのためのドキュメントライティング』の内容を紹介しつつ、「エンジニアがドキュメント作成に苦しまないためのノウハウ」について話されていました。
書籍の構成は以下の3つ。
- ドキュメント作成の準備（読み手の理解）
- ドキュメントの作成（ドキュメントのドラフト）
- ドキュメントの公開と運用（フィードバックの収集と組み込み、ドキュメントの品質測定）
上記の中から、以下のパートについて紹介されていました。
- ドキュメント作成の準備
- 読み手の理解
- ドキュメントの作成
- ドキュメントのドラフト
- ドキュメントの公開と運用
- フィードバックの収集と組み込み
- ドキュメントの品質測定
読み手の理解
大前提として、ドキュメントにより、どんな課題を解きたいか？を考えるのが大事であると強調されていました。
ユーザーを理解するために、以下の手法を紹介されていました。
- チャットでの会話ログ
- プロダクトの設計メモ
- インタビューメモ
- 過去のメール
- コミットログ
ただし、上記よりもユーザーと直接対話するのが一番とのことです。
対話したら知見をまとめて、読み手の人物像を具体化していくのが大切
また、ドキュメントを書く際に嵌りがちな罠「知識の呪い」（認知バイアス）についても話されていました。
「知識の呪い」とは、「おそらく知っていると思いこんでいて必要な情報を伝えていない」ことを表します。
「知識の呪い」を断ち切るためにユーザーへの共感が必要で、ユーザーの嵌りポイントを記録した「フリクション（摩擦、抵抗）ログ」を作るのも有効とのことです。
ドキュメントのドラフト
手を進めるコツとして、とにかく手を動かす、とにかく書く、と話されていました。
これだけ読むと精神論っぽく見えるかもしれませんが、私は書籍やウェブ記事の執筆経験が少しあるので、強く共感できる話でした。
また、文章を書き始める前に、以下について最初に決めるのが大切とのことです。
- 「誰が」「何のために」読みに来るのか？
- 「どのタイプ」のドキュメントが適切か？
次に、タイトルとアウトラインを決め、ユーザーと目的を整理したら肉付けしていきます。ドキュメントの目的はユーザーにとって必要な情報を素早く見つけられる内容にすることなので、以下について留意する必要があるとのことです。
- 流し読みしやすい構成にする
- 最も重要な情報を冒頭で述べる、大きな文章のかたまりを分割する
フィードバックの収集と組み込み
ソフトウェアと同様、ドキュメントもフィードバック（FB）をベースに検証が必要。FBの収集方法として以下を紹介されていました。
- ドキュメントページにフォームを埋め込む
- サポートチケットから読み取る
- ドキュメントに対する感情を集める
- ユーザーサーベイを実施する
- ユーザーコミュニティを作り、そこで質問する
大量に集まったFBは全部対応するのは現実的に不可能なので、分類してトリアージする必要があるとのことです。
ドキュメントの品質測定
ソフトウェアの世界で言われている有名な格言に「測定できないものは改善できない」がありますが、ドキュメントにも当てはまる言葉で、完成後も以下2点の品質について測定することが大切とのことです。
- 機能品質（超重要）
- ドキュメントの目的やゴールが達成されているか？
- 構造品質
- ドキュメントがうまく書かれているか？ 構造は適切か？
最後に
考えてみると、エンジニアがドキュメントの書き方について体系的に学ぶ機会があまりないような気がします。
今回のお話を伺っただけでも、ドキュメント作成は工程を細かく分けなければ目的にかなった成果物は作れないことが分かります。おそらく、そんなに大変な仕事というイメージを持っていなくて、開発の過片手間でやるものと考えている人も多いのではないでしょうか。
ドキュメント作成を上手くできるのはすごいスキルで、いい文章を書けるのは良いコードを書けるのと同じぐらい楽しいという認識が広がるといいですね。
『エンジニアのためのドキュメントライティング』、近日中に必ず読みたいと思います！