良いドキュメントを書きたくなる本を読んだらドキュメンタリアンになりたくなった - じゃあ、おうちで学べる

Tags

Top Highlights

• ドキュメンタリアンとは、役職に関係なく、ソフトウェア業界でドキュメントとコミュニケーションに関心を持つ人のことです。

• 『コードを読めば分かるから、ドキュメントは今は書かなくていいかな？』って言った人はその後もほとんど、ドキュメントを書かない。ちなみにこういう人はコメントもあまり書いてくれない。エンジニアが新たにシステムを理解したいときはいくつかの場面がある。「エンジニアが新たにシステム開発/運用に参加したとき」「エンジニアが自分の担当以外の構成要素や機能を理解したい時」、その他、様々な場面etc…。システムで利用している技術スタックに十分な知見があったとしても、意外に開発を開始までには手間と時間がかかる。

• 機能品質は常に構造品質よりも重視されるようにする。

• 人間は他人が自分と同じ知識をもっていると思い込んでしまいます。

• また、CHAPTER 11　ドキュメントの保守と非推奨化にはドキュメントを容赦なく刈り込む重要性について記載されています。ここがブログなどとは大きく違う点だと思う。そのドキュメントの機能構造が発揮できなくなったら削除したり非推奨にするのが大事です。陳腐化された、ドキュメントは削除する削除できない場合はアーカイブしたり、ステータスとして「廃止予定(Deprecated)」を付与することは本当に大切です。

• 『良いドキュメントとはドキュメントの品質が高いこと、ドキュメントが目的にかなっていること』もう少し品質について分類すると構造品質と機能品質にわけられる。

• 機能品質 ドキュメントの内容がその目的を達成するかどうかを評価します。これには、情報の正確さ、完全性、信頼性、時宜性、明瞭性、関連性が含まれます。

• 構造品質 ドキュメントがうまく書かれているか、うまく構成されているか？ドキュメントの形式、構成、レイアウト、デザイン、文法、綴りなどの側面を評価します。

• 『ユーザーの問題解決とプロダクトの成功を導く エンジニアのためのドキュメントライティング』