[[📚エンジニアのためのドキュメントライティング]] のラフな読書メモ。 # はじめに - ドキュメントがない理由 - [[書き手のループ]]を理解できていないため、ドキュメントをうまく書けないから # イントロダクション - 登場人物 - シャーロット - リード開発者 - 1か月後に開発者向けドキュメントを含む成果物をリリースする役割 - カーティク - ソフトエンジニア - シャーロットの同僚 - メイ - 初期顧客の1人 - アイン - マスコットでありベータテスター # PART1 ドキュメント作成の準備 ## CHAPTER1 読み手の理解 ### [STORY] サービス開始まであと1ヶ月 - 🤔残っていたドキュメントにデジャヴ - メールの寄せ集め - 散在する議事メモとホワイトボードの写真 ### [[知識の呪い]] - [[知識の呪い]]は問題つくっているときに陥りやすい... 『この問題は簡単すぎかな...』と思うと案外そうでもなかったりする ### ユーザーの最初のスケッチを作る - ユーザーがだれであって何を達成したいのか理解する #### ユーザーのゴールを定義する - エンジニアとユーザーのゴールは異なる - ゴールの異なる部分と重なる部分を明らかにする - 🤔ゴールを分割して重なりやすいようにする? #### ユーザーを理解する - ユーザーの定義方法 - 一例としてロール (プロジェクトマネージャー、開発者、システムアドミニストレーターなど) - ユーザーの状況 (余裕がある or 急ぎ など) - ユーザーの熟練度 - すべてのユーザーのニーズを満たすのは無理なので、優先度付けは大事 #### ユーザーニーズのアウトラインを作る - もっとも簡単な方法は『ユーザーが疑問に思う質問のリストを作る』こと ### ユーザーの理解を検証する - ユーザーとの直接対話が大事 - ユーザーのニーズに焦点をあてる... ==ウォンツではない== #### 新しいデータを集める - インタビューは量より質、3～5人で十分 ### ユーザー調査から得られた知見をまとめる ##### [[ユーザーペルソナ]] - ガイドや説明を必要とする人から重点的に取り組むのが良い ##### [[ユーザーストーリー]] - よく使うフォーマット - 『あるユーザー』として『あるゴール』を達成するために、『ある活動』をしたい - 『APIの使い方を知りたい』『〇〇なドキュメントが欲しい』==とかではない== ##### [[ユーザージャーニーマップ]] ### まとめ ## CHAPTER2 ドキュメントの計画 ### [STORY] 計画の作成 ### 計画とパターン - ユーザーがゴールを達成するためのユースケースが大事 ### コンテンツのタイプ #### コードコメント - 開発の意思決定を書く - 複雑なシステムはコードが自己文書化されることは滅多にない -