楽しみにしていた「エンジニアのためのドキュメントライティング」を読んだ。
ストーリーが読みやすい。
本書で想定されているドキュメントを日常的に書くという感じではない。
それでも MTAppjQuery のドキュメントとかはあるし、日常的には案件のドキュメント的なものは色々と書くので、参考にしようと思うところが多かった。
案件のドキュメントは対象とかは無意識で進めているが、目的とかは意識して書く・整理しないとだよなぁと。
日常的に読んできている人が知りたい時の視点
途中から入ってきた人、前提知識がまだ無い時の視点
特定のことを調べたい場合の視点
様々ある訳なので最初に意識する所は変わってくるはず。
書く内容、リンクの仕方、それぞれのドキュメントの構成。
ドキュメントを書く際に意識していくためには、各ドキュメントの最初に目的とかを明示して置いてもいいのでは無いか？という気もした。
ドキュメントを読んでもよくわからないという状態はできるだけ避けるべきだし、そもそもドキュメントが書かれていないとかは問題外だと思うのでそうならないようにしないと。
Wiki や GitHub とかでの markdown ファイルが基本にはなるだろうけど、 Obsidian Publish , Scrapbox 的なものの方が使いやすいとかもあるのかもしれない。
この辺は編集のしやすさをどこまでとって、更新ログとかをどうしたいかとの塩梅によっても決まりそう。