あとがき公開「エンジニアのためのドキュメントライティング」
2023/3/11(土) に「Docs for Developers: An Engineer’s Field Guide to Technical Writing」の翻訳書籍である「ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング」が日本能率協会マネジメントセンター(JMAM)社より刊行されます。
今回、JMAM社に許可をいただいて書籍のあとがきを公開できることになりました！本記事では以下に、あとがきを先行掲載します。
あとがき
- 「ドキュメントを書いておけば良かった」
- 「ドキュメントは書いてあったけど、2年前に更新が止まっている」
開発の中でこう思ったことは、何らかの形でプロダクトやシステム開発に携われている方であれば、少なくとも一度はあるのではないでしょうか。 たとえば、「設計上の意思決定の経緯が残っておらず、加えたい変更の影響範囲が分からなくて困っている」もしくは「過去に実施した手順が残っていなくて再現に時間がかかってしまう」といったようにさまざまなパターンの経験があるでしょう。
一方で、エンタープライズ系の経験がある方は次のように思ったことがあるかもしれません。
- 「なんで、こんなに大量のドキュメントがあるんだろう」
- 「本当にこのExcelで作られたマニュアルは使われているのだろうか？」
使われないドキュメントを大量に生み出しても意味がありません。 さらに、使われないドキュメント自体のメンテナンスコストが発生しますし、時代遅れとなった情報が顧客に伝わってしまいます。
もし、ドキュメントの情報が古くて誤りがあっても、そのプロダクトやシステムを顧客が使い続けてくれるでしょうか。 社内システムなどで利用が強制されるシステムでない限り、おそらくそのプロダクトを使うのをやめてしまうでしょう。 社内システムであったとしても、従業員体験を著しく悪化させるため、長期的には良い結果とならないことは明白です。
重要なのは、ドキュメントの利用者にとって本当に価値のあるドキュメントを作成・保守して提供し続けることです。 そのためには顧客やユーザーを理解する必要があります。 顧客の課題が分からなければ、価値のないドキュメントを生み出してしまうからです。
では、価値のあるドキュメントをどのように生み出せばよいのでしょうか？
エンジニアの本業はシステムを設計し、実装することです。 そのために、さまざまな手段を通じて開発スキルを見つけてこられたと思います。
一方で、本書で扱ったような体系的なドキュメントライティングの方法を学んできた方は少ないはずです。 仮に大学で学んでいたとしても、「APIを廃止にするためのドキュメント」については教えてくれなかったでしょう。
もちろん、企業によっては、ライティング専門の部署が存在することもあります。
たとえば、LINE株式会社には「テクニカルライティング」の専門チームが設置されています1。 また、サイボウズ株式会社にはテクニカルライティングを担うテクニカルコミュニケーションチームが設置されています2。 こうした事例から、日本でもその重要性が認識されて始めていると言ってもよいでしょう。
しかし、すべての企業が同様の部署を配置できるわけではありませんし、配置したとしてもすべてのドキュメント作成を担えるわけではありません。 実態としては、スタートアップであれば人員が限られているため、エンジニアがドキュメント作成の役割を担うことがほとんどでしょう。 大企業であっても、さまざまな環境制約から現場のエンジニアがドキュメントを作成しているケースが多くあると思います。
本書の原題は、「Docs for Developers - A Field Guide to Technical Writing」です。 まさに現場のエンジニアのための書籍になっています。 本書をここまでお読みになった方は、業界の第一線のエキスパートが共有してくれた知見を武器に、 ドキュメントを書く知識やスキルが備わりはじめているはずです。
しかし、実践無しにライティングのスキルは高まりません。 実際に著者の一人である、サラ氏は「ドキュメントライティングのスキルを高める方法の1つは、実際に書くことだ」とおっしゃっています3。 つまり、価値のあるドキュメントを作るには本書をもとに実践することにほかなりません。
今日から実践して、より効果的なドキュメントを生み出していきましょう！
本書を手に、ご自身を取り巻くプロダクト開発の現場が少しでも良くなり、 ひいては日本のプロダクト開発全体が少しでも良くなることを願っています。
ということで、 2023/3/11(土) より販売開始されます！Amazonなどでお買い求めいただけます。日々の開発や運用に活用いただければ幸いです！