ピクトリンク事業部の橋本です。
『ユーザーの問題解決とプロダクトの成功を導くエンジニアのためのドキュメントライティング』を読んだので、今回はそのご紹介をさせていただきます。
ドキュメンテーションに対する考え方や評価基準などが学べたほか、重要性の再認識もでき、様々な収穫のある一冊でした。
この本を読むきっかけ
フリューでは長年にわたり、いくつものサービスを運営しています。
仕様書、設計、運用手順書、バグレポート、よくあるエラーとその対処法。その他もろもろのドキュメント類がサービスごとに存在しており、その総数は膨大な数にのぼります。
そして、たびたび
- 内容が古い。最新の手順に追随できていない(陳腐化)
- 探している情報がどこにあるかわからない。あるかどうかもわからない。
- なんのためにあるのかわからない記述(書いた当時の動機が不明)を、削除や改修して良いか判断がつかない(のでそのままにされる)
といった、いくつかの問題を抱えてきました。
ドキュメントとして残されていても、残念ながらそれが使いやすい状態で保たれているとは限らないのです。
今後、ドキュメンテーションに力を入れていくにあたり、この本を読んでみることにしました。
本書は、上記と同様のことにお悩みの方や、ドキュメンテーションの必要性を認識しながらも何から手をつけていいか迷っている方、プロダクト文書作成の基礎から学び直してみたい方に特におすすめです！
どんな本？
タイトルの示すとおり、本書はエンジニアがドキュメントを書く際に意識すべきことを順序立てて解説しています。
中身は大きく３つのパートで構成されています。(イントロダクションを加えると４つ)
- イントロダクション
- PART1 ドキュメント作成の準備
- PART2 ドキュメントの作成
- PART3 ドキュメントの公開と運用
PARTごとに、さらに細かくChapterに分割されています。
本書は翻訳本です。
原著は『Docs for Developers: An Engineer’s Field Guide to Technical Writing』というタイトルで、執筆陣の中にはGoogleやStriipeで活躍するエンジニアもいらっしゃるようです。豪華〜。
架空の『犬の鳴き声を翻訳するAPI提供サービス』のドキュメントを作るていで進行します。
もしかしてDocsとDogsをかけてたりするんでしょうか。
印象に残ったポイントまとめ
印象に残った部分と、それに対する感想をPART別にご紹介します。
イントロダクション
- ドキュメントの優先順位が、サービスの実装などと比べて低く設定されることがある。これは、多くの人がドキュメントの作り方や重要性を知らないからである。
- ドキュメントの有無はサービスの挙動に直接寄与しないため、後回しにされたり、「おまけ」のような扱いをされがちという話。
- 大事な仕事なので、「余分」な、もしくは「追加」のタスクと捉えてはいけない。
- 「可読性に十分に配慮されたコードは一種のドキュメントである（そのため、別途ドキュメントを作成する必要はない）」という考えが成り立つ場面はあるが、規模が大きいプロダクトでは難しい。
- コードのコメントもドキュメントのひとつ。コード上には現れないコンテキストを残しておくと捗る。
- なぜそういう対応にしたのかとか、当時を知らないと意図が汲めなかったりするため。
- コードのコメントもドキュメントのひとつ。コード上には現れないコンテキストを残しておくと捗る。
耳に痛い話もちらほら出てきます。
冒頭の一節、
READMEには見出しと"TODO"って一言書いてある段落しかない。
「誰が書いたんだよ、これ」
と考えて気分が沈んでいく中、１４ヶ月前に書いた自分のコードだったことに気づく。
「全然覚えてない」
には全米が泣きましたね……。(※個人の感想です)
２ヶ月以上前の自分はもはや他人。
ちゃんとしたドキュメントを残すのは、仲間のメンバーだけでなく未来の自分のためでもあります。
「情けは人の為ならず」ってところでしょうか。
実際に「書く」行程だけではなく、作成計画や、実際に書いたあとの運用まで含めてのドキュメンテーションである、と述べているのが印象深かったです。
あと、挿絵のコーギーがかわいい。
PART1 ドキュメント作成の準備
- ドキュメントもひとつのプロダクトである。
- 誰向けのドキュメントを作るべきかを考える。
- ペルソナ、ストーリーマップ、ジャーニーマップを定義して離脱ポイントやストレスを感じる部分を明確化していき、適宜手厚くする。
- 想定ユーザーのニーズ(needs)に焦点を当てる。ウォンツ(wants)を混同したくなるけど切り分ける。
- ほんとに商品開発と同じ感じですね。
- そのドキュメントを読んだユーザーがどうなってほしいのかゴールを明確にしておく。
- 中身がブレにくくなる！
- 『知識の呪い』を知ろう。
- 自分の知っていることは、他人も知っていると思いがち。
- 想定読者の知識レベルに合わせて、説明の『深さ』を調整すべし。
- エンジニア向けの文書と、プロダクトマネージャ向けの文書は違うはず。
- 無理にひとつで賄おうとすると、逆に両者にとって使いにくいものになる(そして、使いにくいと見てもらえない)。
- 読者は思ったより文章を読んでくれない。
- たいてい、欲しい情報を検索してやってくる。細かい文章はあまり読んでもらえない。
- あれもこれも補足情報を書きたくなるけど、必要な情報に絞り込む。
PART1では全体的に、ドキュメントに向かい合う意識付けや、観点を補ってくれる内容となっています。
コーギーの挿絵がかわいい。
PART2 ドキュメントの作成
- 『空の文書』をどうやって埋めるか？
- 「はじめに」から書く必要はない。書けるところからざっくり書いていこう。
- 良い文章の構成、良いコードサンプルとは
- ビジュアルを有効活用しよう
- 「絵は千の言葉に値する」という言葉。「百聞は一見にしかず」みたいなもの。
- ただし、文章よりも更新コストがかかるので、全部を図にすればいいってものでもない。
- 一枚の図になんでもかんでも詰め込んではいけない。必要な部分にフォーカスして、簡潔に。
- 「美しいドキュメントは、短くて簡潔です。」
- コーディングでもたびたび聞く話ですね。
PART2では、実際に文書を作成するにあたってのTipsが多く書かれていました。
体感的にふんわり捉えていたものを、整理して言語化してくれている感覚でした。たまに本棚から引っ張り出して再読したいです。
それと、コーギーの挿絵がかわいい。
PART3 ドキュメントの公開と運用
- ドキュメントを公開するのはプロダクトと同等の考え方をしよう。
- PART1で触れた内容の念押し
- プロダクトリリースと同様に、ドキュメントリリースのプロセスを構築する。ガントチャートを作ってみるのもいい。
- プロダクトと同等 = リリース前のテストもやる。
- ユーザーからフィードバックを得よう。
- ドキュメントの品質評価
- 『機能品質』と『構造品質』という考え方。
- PART1で設定したゴールを達成できているかの測り方。
- ドキュメントオーナーを指名しよう。
- プロダクトオーナーと同様に、ドキュメントの品質を担保し、最終的にGoサインを出す責任者を設ける。
- ドキュメントの構成仕方
- サイトマップやナビゲーションなど、ユーザーが必要な情報に辿り着けるようにする仕組み。
- 5分くらい探せば必要な情報に行き当たれるようにしておくべし。
ドキュメントの責任は全員にある、それゆえに誰も責任を負ってないとも言える。
ドキュメントオーナーの必要性が、この一文に集約されているように感じました。
「できる人が、できるときにやる」だと個人のセンス依存になってしまってよくない。
ドキュメント作成は各メンバーがやるとしても、大将が責任を持って統括するべし。
そして、コーギーの挿絵がかわいい。
まとめ
実践可能なノウハウがたくさん詰まっていて良かったです。
とくに、弊社で抱えていたドキュメントの陳腐化などの諸問題は、ドキュメントオーナーを指名することで改善していけそうです。
ほかにも、ドキュメントもプロダクトと同等の考え方をするというのは、今後のドキュメンテーションにおける重要な指針になると感じました。
なんとなくですが、コーディング(開発) = 理系分野、ドキュメント(文書化) = 文系分野のようなイメージで、これまでは漠然とした畑違いの苦手意識みたいなものがあるような気がしていました。
しかし、ドキュメントも設計、テスト、リリース、運用といった開発者にも馴染みあるフェーズにブレイクダウンすることで、取り組みやすくなる……といいな！ と思います。
できる部分から取り入れて実践していき、また折を見て読み返したい一冊でした。
また、本書が面白かった方には、「理科系の作文技術」もおすすめです。個人的バイブルのひとつです。
「ドキュメント」って書きすぎてゲシュタルト崩壊してきたので、今回はこの辺で。
