参考にした記事など
具体的に書く
何が、なぜ、どのように、などを具体的に書いて、わかりやすくする
画面名、URL、などの情報は出来るだけつける
例)レビューチケット(backlogとか)
-
どこをどのように修正したのかを明確に示す
- ドキュメントの修正なら、何行目、とか項目名○○、とかパっと移動できるような情報を示す
- コードの修正なら、行数を書いておき、修正箇所をコピペで張るとかするとわかりやすい気がする
-
修正の理由（背景）を書く
→レビュワーはどこを見ればよいかがすぐわかり、その修正の妥当性についても書いてある理由から判断できる
定量化する
明日→2023/1/11
数分→5分
前提(理由)を書く
例えば仕様書を見てこの処理いらなくね？と思うのがあっても、実は必要な理由があったりする
そういうのを書いてくれていると後から入ってきた人にも伝わりやすい。
前提を知らない人が修正して、バグになっちゃうかもしれない。
ただ、書きすぎても…
要件を簡潔に伝えた方が分かりやすい場合もある。
伝言とか依頼とかは「結局何をすればいいの？」「結局どうなったの？」がわからないとつらい
分かりやすい言葉で書く
自分ははじめ、渡された資料の中に意味の分からない略語があった
一般的ではない略語（プロジェクト内で使われているものなど）を使用する場合は、文書内で初めて出てくるときには説明を入れておく。
→後から入ってきた人にも伝わりやすい。
表記漏れは混乱を生むのでなくす（用語を統一）
箇条書きを使う
箇条書きにすることで、各項目が独立し全体イメージが把握しやすくなる。
修正点は以下の３点です。
・ほにゃほにゃ
・ほげほげ
・むにゃむにゃ
※特に箇条書きが入れ子構造になる場合は、インデントにも気を付ける
・ほげほげ
・ほげほげ２
・ほげほげ３
・ほにゃほにゃ
・ほにゃほにゃ２
打消し線も活用する
消すより打消し線を使った方が、流れがわかって良い場合がある
~~ほにゃほにゃほにゃほにゃ~~
【追記】2023/1/10の打合せで、上記は行わないことになりました
理由は～～～～
これっていつ決定したんだっけ？昔と変わったんだっけ？なんでだっけ？を知りたい時があるよね
既存のドキュメントを踏襲する
テンプレートがあったりするのでそれを利用することで書式がそろって見やすくなる
何も考えずに既存のドキュメントをコピーしない
既存のドキュメントを流用する場合でも、わかりにくいと感じたところ、不足していると感じたところは追加する。
元々こうだったので、、とか、誰々さんがこう書いていたので、、とかは良くない。
まとめ
結局は、他の人が見たときにどう思うか？と客観的に見ることが大切。
自分が分かるだけでは意味が無い。