ドキュメントが無いなと頻繁に思うけど、まず書けないんだなと思ったので読んでみた。
目次は以下
CHAPTER 1 読み手の理解
CHAPTER 2 ドキュメントの計画
CHAPTER 3 ドキュメントのドラフト
CHAPTER 4 ドキュメントの編集
CHAPTER 5 サンプルコードの組み込み
CHAPTER 6 ビジュアルコンテンツの追加
CHAPTER 7 ドキュメントの公開
CHAPTER 8 フィードバックの収集と組み込み CHAPTER 9 ドキュメントの品質測定
CHAPTER 10 ドキュメントの構成
CHAPTER 11 ドキュメントの保守と非推奨化
読み手のことを考えなければいけないということを、書いているときには忘れてしまうことが多い。
たとえば、自分が所属しているチームで考えると、やれることがたくさんあるので何ができるかを書かなきゃいけないと思う。そのときにまず書き始めるのものが、リファレンスみたいなものが多い。しかし、使う人がエンジニアなどでない場合、APIの仕様やツールの使い方を事細かに説明されていたとしても、読み手からこれはどういう意味ですかと聞かれることが確かに多かった。これは、読み手の能力を考えてない問題な気がする。
その他にも、事細かにパラメータの説明などが書かれているが、これはまず何ができるのか？がわからないようなドキュメントもよくあるなと思った。これらも、自分たちが分かっていることや使うときに、ここの値を使うだろうからという気持ちで書いているが、まず何ができるのか？自分たちがやりたいことが実現できるのかを知りたい人にとっては読みにくいものになっているだろうなと思った。これは読む人の目的を考えてない問題だったと思う。
ドキュメントのタイプとしては以下が紹介されている。
- コードコメント
- README
- コンセプトドキュメント
- 手順書
- チュートリアル
- ハウツーガイド
- リファレンスドキュメント
- API リファレンス
- 用語集
- トラブルシューティングドキュメント
- 変更に関するドキュメント
これらのドキュメントで何を表すか、誰に読んでもらう想定なのかを考えながら書き分けるのが必要なのだろう。１つにまとめてしまうと結局読みにくいものになってしまうと思うので、解決したいものに合わせて書き方を選び、書き分けていくのが大事そう。
そして、ドキュメントの品質、保守、フィードバックについての話はとてもおもしろかった。
ドキュメントも製品だと考えるとたしかに品質が良いものが好まれるに決まっている。そのためにはドキュメントの品質について考える必要があり、本書では機能品質と構造品質で考える方法が紹介されていた。しかしこのあたりについては書くドキュメントの目的によっても変わってくるだろうから、自分で書くときに何を目的としているかを考えそれが達成できているか、どう計測できそうかを考えていきたい。
また、ユーザから積極的に意見をもらえる環境を作っておくことも大事だと読んでいて思った。フィードバックをもらうことはたしかに難しい。どうでしたかと聞いても大抵の人は意見を返してくれないのでうまく受け取れるような仕組み、よく返してくれるコアユーザなどを作っておくことは大事だろうな。
古くて役に立たないドキュメントがたくさん残っているなとチームのを見て思っている。書いて終わってしまうことが多く、後々忘れた頃に見てこんなこと書いてたなとか、もう間違っているなと思うこともたくさんある。また、ドキュメントのリンクが切れてしまっていることも確かに多い。本書で紹介されているように、見直すタイミングを考えるや非推奨化という形で告知してから消すというのは勉強になったしやらないといけないことだなと思った。うまく更新される仕組みを考えていきたい。
読んだ感想としては、ドキュメントもソフトウェアの開発のように考えるのが良さそうということ。どういうユーザに対して書いて、どのような構造で書くか決めて、実際に書いてみて、ユーザに読んでもらってフィードバックをもらって改善していく。結局だれかに提供するものを作っているものなので、開発サイクルを回すような考え方になるのだろうなと思った。
まとめ
- まずはとりあえず書いて公開するところから初めてみる
- なにに対しての文章なのかを決めてから内容、書き方を考えてみようと思った
- テクニカルライティングというポジションがあることを知った
