読書感想文「エンジニアのためのドキュメントライティング」
概要
書籍「エンジニアのためのドキュメントライティング」を読了しました。
読書感想文を書いてみます。
読もうと思った背景
自分は、仕事にて文書作成で度々苦労していることもあって、文書作成が苦手であると自覚しています。
そんな苦手を克服するべく、文書作成系の本を幾つか読了してきました。
読了の度に、何らかの知見を獲得でき、少しずつですが改善できているように感じています。
そんな苦手の克服の一環で、本書に目を付け、読むことに決めました。
本文 概要
以下の三部構成です。
- ドキュメント作成を計画する
- ドキュメントを作成する
- ドキュメントを公開し、運用・保守する
第三部が「公開および運用・保守」に焦点を当てていることか分かる通り、書籍全体としてドキュメントの公開を前提としています。
そのため、非公開ドキュメント（社内でのみ使用するなど）の作成では、やや過剰にに感じる手法もあります。
教訓・学び
書籍内では、ドキュメントの目的を「読み手の目的達成を手助けするもの」と、一貫して表現しています。
- 読み手の目的達成を手助けするために、読み手のことを知る
- 読み手の目的達成を手助けするために、フィードバックを得て改善する
- 読み手の目的達成を手助けするために、目的のコンテンツにたどり着きやすい構成を考える
- 読み手の目的達成を手助けするために、運用・保守にて目的達成を阻害するものを改修・削除する
- などなど
この考え方は、ドキュメントの公開・非公開に関わらず共通する、非常に有益なものだと感じました。
ドキュメント作成における、一つの不変な方針になりそうです。
◇◆◇◆◇◆◇◆
ドキュメントの品質を検証するにあたり、ドキュメントの品質を、本書では以下二つのカテゴリで分類しています。
- 機能品質 : ドキュメントの目的やゴールが達成されているかどうか
- 構造品質 : ドキュメントが上手く構成されているか、読みやすいか
こういった分類の観点は考えたこともなく、目から鱗でした。
そして、ドキュメントの目的「読み手の目的達成を手助けするもの」という観点から、「機能品質」の方が重要であると述べています。
また、「レビューの際は構造品質に目が行きやすい」という注意事項も指摘されています。
こちら身に覚えがある指摘で、納得感がありました。
◇◆◇◆◇◆◇◆
本書で紹介しているドキュメント公開までの流れは、大雑把に言えば、以下の通りです。
- ドキュメント作成を計画する
- 計画通りに作成する
- 想定読者へのレビューにてフィードバックを獲得する
- フィードバックを基に改善する
こうしてまとめると、スクラム開発にてプロダクトを開発する流れにそっくりだと感じました。
このことから、自分の中では「スクラム開発でプロダクトを開発するような流れで、ドキュメントも作成（むしろ開発？）すると良い」というようにまとめることが出来ました。
◇◆◇◆◇◆◇◆
本書では、以下のような記述がありました。
また、フィードバックでは素晴らしかった部分を伝えてもよい。
素晴らしい文章を取り上げることで、他の人がまねできるようになる。
レビューとなると、アレコレ指摘する事ばかりに目が行きがちですが、「ここいいね👍」と褒めても何の問題もなかったです。
むしろ、良かった箇所をチームに共有することで、チームの能力向上にも寄与しそうです。
無意識に、「レビューなら指摘しなきゃ」という先入観が働いていました。
今後レビューを行う際は「ここいいね👍」を意識してみたいと思います。
Discussion