こんにちは、んだです。
今回のテーマは「ドキュメントライティング」です
なぜ読んだのか？
これまでの経験の中でドキュメントらしきものは作ってきましたが、本などを通じてきちんと学んだことはありませんでした。
ただ以前から「ドキュメント」というものに対して以下のような疑問を持っておりまして
* ドキュメント作成の効率を上げる方法は？
* ドキュメントの質を向上させるにはどうすればいいのか？
* どうすれば、古くなって役に立たなくなるドキュメントを防げるのか？
* ドキュメントの保守についてどのように取り組めばよいのか？
この本は、この疑問に十分答えを提供してくれるものでした。
ただ、その答えは「目から鱗」的な思いも寄らないものではなく、言われてみたら当然だなと思うようなアプローチが多かったです。
例えば、ドキュメント作成において、読み手を理解することが大切だというアドバイスがありました。 これは当たり前のことのように聞こえますが、実際に作成していると、自分の視点や知識を前提にしてしまいがちです。
また、本書はポイントの列挙ではなく、物語仕立てになっているのも想像を掻き立ててくれてよかったです。
Corg.lyという仮想サービスのドキュメントを作成するというストーリーが本書を通じて展開されるのですが、ドキュメントが少しづつ完成されていくステップが想像できて、ここもグットなポイントでした。
読んでよかったと思う点
ここからは、読んでよかった点について掻い摘んでお話ししていきます。
僕の以前から抱いていた以下の疑問に対する解決策が、そのまま「読んでよかった点」になったので、それぞれについて順に書いていきます
- ドキュメント作成の効率を上げる方法は？
- ドキュメントの質を向上させるにはどうすればいいのか？
- ドキュメントの保守についてどのように取り組めばよいのか？
ドキュメント作成の効率を上げる方法は？
まず、ひとつのトピックは
「効率的にドキュメント作成をすすめるには、どうしたらよいか？」
についてです。
本書では作成にあたり、さまざまなアプローチを紹介しているのですが、僕が特にグッときたのは
- 読み手の理解とゴールの設定から始める
- アウトラインから書き始める
でした。
読み手の理解とゴールの設定から始める
読み手の理解
本書では、一発目に「読み手の理解」の話題が登場します。
ドキュメントって誰のものかってゆうたら、書き手ではなく読み手ですよね。では、読み手のことを理解して、さらに意識しながらドキュメントを書く姿勢が僕にあったかと言えばノーノーノーです。
本の中では、ペルソナやユーザースケッチなどの話が登場するんですが、そこまでしなくとも、読み手はだれで、どんなことを求めてこのドキュメントを読むのか、この部分に焦点を当てるのは、作成の質をあげるなと感じました。
ゴールの設定
引用です。
そもそも、なぜドキュメントを書く必要があるのでしょうか？それは、ユーザーに何らかのタスクを完了してもらいたいもしくは何らかの方法で行動を変えて欲しいからです。
ドキュメントは単なる情報の羅列ではなく、読み手が何かを達成するための手段。言われてみると納得しかないのですが、普段そのことを骨の髄まで意識できてなかったっすね
ドキュメントを作成する際には、常にこの目的を意識し、読み手にとって最適な情報を提供することを目指すのが基本姿勢ですね
さらに、ゴールと読み手の設定、はじめにここを設定することで、作成の過程でブレがなくなりそうです。
アウトラインから書く
ドキュメント書くときに、何から始めると効率的に書けるのかに対するアンサーです
本書では、「白紙からの脱却」というワードが登場するのですが、白紙の状態からスタートするのは、どうしてもハードルが高く感じてしまいます。
しかし、アウトラインから書いちゃえと思ってまずは手を動かせば、スムーズに進むのではないでしょうか
で、実際アウトラインを立てる際には、まずは、必要な要素を順不同で書き出して、その後に整理してアウトラインを作成すると良いと述べています。
こうすることで全体像が見えてきますし、アプローチとしてはすごく良いなと思いました。
ドキュメントの質を向上させるにはどうすればいいのか
次のトピック
「ドキュメントの質を向上させるにはどうすればいいのか」
についてです。
本書では、編集の仕方やレビューの観点など、さまざな方法を紹介していますが、僕としては、ドキュメントの質を図る２つの観点がグッときました。
ドキュメントの品質について考える際、
「機能品質」
「構造品質」
という２つの品質があると紹介されています。
機能品質 →ドキュメントのゴールや目的が達成されているかどうか
構造品質 →ドキュメント全体がうまく書かれているかどうか、うまく構成されているかどうか
です。
本書では、どちらも重要ではあるものの、機能品質が優先されることが強調されています。つまり、ドキュメントのゴールであるユーザーのタスク完了や行動変容に合致していることが最も重要であるということです。
ドキュメントの質を向上させるには、機能品質と構造品質の両面からアプローチすることが必要で、この観点を学べたことが収穫でした。
ドキュメントの保守についてどのように取り組めばよいのか
最後は
「ドキュメントの保守についてどのように取り組めばよいのか」
というテーマです。
本書では、以下のようなアプローチが提案されています。
- リリースプロセスの中にドキュメントの更新を組み込む
- ドキュメントオーナーを決めて、責任を明確化する
- 一定期間更新されていなければ、オーナーにメールなりメンションを飛ばす
- 削除する
ドキュメントの保守について、何らかのアプローチを学んだことがなかったので、大きな収穫でした。
よく聞く「古くなって役に立たないドキュメント、嘘が多くて信じられないドキュメント」なんてワードは聞いたことがあるかもしれませんが、ドキュメントの更新を忘れてしまったり、保守が行き届かなくなってしまうことは、チームで作業を行う上で避けて通れない課題ですよね。
リリースプロセスの中にドキュメントの更新を組み込む
本書で、まずは、リリースプロセスの中にドキュメントの更新も組み込んでしまうアプローチが紹介されています。
ドキュメントが整理されている且つリリースする機能がどのドキュメントに関連しているかがわかっていれば可能でしょうが、、これ良さそうですが、実現するにはなかなかむずそうです。
とはいえ、たとえばissueのテンプレの中にドキュメントの更新の欄を作っておいて、など開発フローに組み込んでみるのはアリかと思いました。
ドキュメントオーナーを決めて、責任を明確化する
ドキュメントオーナーを決めて、一定期間更新されていなければ本人にメンションを送るなど、保守の責任を明確にするというアプローチも良きかと思いました。
ただし、これも仕組みがあれば解決ではなく、仕組みはあくまでも仕組みであってやはり本人のドキュメントに対する意識を高く維持しておくこと、開発に対してドキュメントを更新するゆとりをもたせるという別の問題が絡んでおるなと感じました
また、更新だけでなく、リリースによって不要になった部分は削除することも忘れずというのも、その通りの通りでした
ドキュメントの保守について、結局のところは意識だったりドキュメントまわり以外の部分が関係するなと思いましたが、アプローチをいくつか知れたことは大きな収穫です。
まとめ
本書を読んで、ドキュメント作成について、いろんな視点やアプローチが学べました。
特に、以下の疑問について解決策が紹介されていたことは、読んでよかった点でした。
- ドキュメント作成の効率を上げる方法は？
- ドキュメントの質を向上させるにはどうすればいいのか？
- ドキュメントの保守についてどのように取り組めばよいのか？
これまで、ドキュメントについての本は一冊も読んだことがなかったですし、この疑問についてきちんと考えてみたこともなかったので、とても有意義な読書経験でした。
メルカリに出さずに持っておこうと思います、僕から以上。あったかくして寝ろよ
