どんな内容か

この本は開発したプログラムのドキュメントの書き方について詳しく紹介している本です。

作ったプログラムやソースを他の人に使ってもらうというのはプログラミングをしている人ならかならず通る道かと思います。ただ、ドキュメントを書こうとなったとき、何からはじめればいいのか途方にくれたことはありませんか？

この本ではそんなドキュメントを書き始めるとなったとき、どのようなことを考えて何をしていけばいいのかの計画から始まり、ドキュメントの作成、品質測定などの保守に関してまでドキュメントにかかわる一連の流れを仮想的なプロジェクトを例にとりながら紹介しています。

例に使っている仮想的なプロジェクトはWebアプリケーションですが、OSSのドキュメントなどプログラムに関する一般的なドキュメントに使える話になっていると思っています。一方、一般的な話のみしか紹介されていないため、Pythonなど特定の言語で特徴的なドキュメントに関する仕組みを使ったドキュメントの書き方などに関しては書かれていないので注意してください。

どんな人におすすめか？

この本は以下のような人にはおすすめだと思います。

1. 新規開発したプログラムのドキュメントを作ることになった人
2. 既存のドキュメントの保守をすることになった人

本の構成としては前半はドキュメントの計画から説明されているため、新規にドキュメントを書く必要がある人向け、後半はドキュメントの保守について書かれているため、既存のドキュメントの保守をする人向けかなと思っています。

プログラムを作ったら誰かに使ってもらうというのはほぼ必ず発生するイベントだと思うので、そういう意味ではプログラムを書くエンジニアは一度読んで、その後は必要になったら参照するという使い方が良いかと思います。

個人的によかった点

個人的に読んでと買った点としては以下の通りです。

1. ドキュメントを作る際にどのような流れで考えていけばよいか分かった
2. ドキュメントの評価に関して知ることができた

今までプログラミングの書き方などに関する書籍は何冊も読んできましたが、ドキュメントに関する書籍はほとんど読んできませんでした。このため、ドキュメントを書く際は試行錯誤しながら書いていました。この結果、手戻りが多く、書くのに時間がかかっていた印象です。それが、今回この本のおかげでどのような流れで考えてドキュメントを作っていけばいいかが分かったため、今後はスムーズにドキュメントを作成できそうです。

また、ドキュメントを作ったはいいけど、いいドキュメントなのか？という疑問が頭をよぎることがたびたびありました。ただ、どうしていいのかわからなかったので基本は放置してました。これに対して、今後は本を参考にドキュメントの評価を行ってより良いドキュメント作りができないかを考えていけそうだなということを思っています。

終わりに

今回はドキュメント作成に関する「ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング」を読んだ感想をまとめてみました。ドキュメントに関する良い本をあまり知りませんでしたが、今回の本はいろいろな人に勧められるいい本だなと思っています。

毎週月曜日にこのような感じで読んで面白かった本の紹介記事をあげていきたいと思います。

The post [書評] ユーザーの問題解決とプロダクトの成功を導く　エンジニアのためのドキュメントライティング ー 開発したプログラムのドキュメントを書こうと思ったら読む本 first appeared on まったり勉強ノート.