開催しましたって書くと大げさですが、顔の見知ったメンバー数人でクローズドなオンライン飲み会勉強会を行いました。
前回はコチラ
toshimana.hatenablog.com
今回は「ドキュメントインスペクション」をテーマに議論しています。その時の学びをまとめておきます。
大きく2部構成で行いました。
- @Unity1004 による「伝わりやすい文章」についての講義
- ドキュメントレビュー大会
その１：「伝わりやすい文章」についての講義
@Unity1004 に良い文章を書くための色々な観点を教えていただきました。特に、レビューする側としてどういうところを見るか、という視点で色々まとめてくださいました。
勉強になることがたくさんあったのですが、特に興味深かったのは以下の2点です。
これまで作成した文章で困っていた項目をまとめておこう
- 「伝わりやすいか」とか「情報の過不足がないか」などといった読み手の負担になるような項目を整理しておくと、どういう観点でレビューする側がドキュメントを見るのかが明確になり、良い指摘が出しやすくなる。
- 上記項目を「明確性」や「妥当性」のように～性としてまとめておくと良い。また、その中で優先度をつけることで、今何をレビューするかをチームで認識合わせしやすくなる。
- どのような項目が必要かは文章の種類や位置付けなど、状況によって異なる。自分たちが何に困っているかをチームで議論して、自分たちの項目を出そう。
書く前に文書設計をしよう
- 文章を書くときは、いきなり書き出すのではなくて事前に情報を整理することが重要。
- 「誰が」「何の為に」読む文章なのかを明確にする。
- それを満たすために必要な情報を洗い出して、伝えるべき内容とそのレベルを検討する。
- 特に「誰が」「何の為に」が定まらないと内容が収束せずに手戻りが発生しやすくなる。
その２：ドキュメントレビュー大会
あるドキュメントをベースに、みんなはどんなレビューをするか、っていうのをやりました。レビュー方針として「パラグラフ(段落)レベルの指摘を重視」することが挙げられました。全体構成の問題を先に洗い出すことで手戻りを減らすことが目的です、
出てきた観点は以下のようなものがありました。
誰の視点の言葉か
- 人が話した内容を引用したりするときに、主語が書き手なのか話し手なのかが分かりにくくなる場合がある。主語が誰かを明確にしよう。人の話を長文で引用するときは、段落で分けるなど区切りを明確にするといい。
情報の過不足がないか
- 文章を見る相手に過不足ない情報を与えて、内容を整理しやすくする。情報不足は情報の前後関係を適切に理解することができなくなる。情報過多は本筋以外の情報の関係が出てくるので整理が難しくなる。今回は特に読み手に関係のない情報がいくつか挙がっていた。
運営：準備不足
オンラインで勉強会をするのは2回目ですが、前回に比べて準備が不足していました。1回目が上手く行ったという油断があったのでしょう。貴重な時間を割いて参加してくれる人たちに余計な負担は掛けたくないので、しっかりしないといけない所です。
事前の連絡手段が複数存在していたため、情報が適切に伝わらなかった
- 対策：全体への連絡手段は一本化する。
タイムスケジュールがグダグダだったので、脇道に逸れやすかった
- 対策：簡単でいいので、やることを洗い出して事前にタイムスケジュールを用意する。
まとめ
伝えたいことが正しく伝わるドキュメントは誰もが求めるものです。しかし、それを作るためにはみんなで知恵を集めて、各々の感性を技術に昇華して、どうすれば良い文章が書けるかを切磋琢磨して考える必要があります。文章作成は未だにいろんな人が苦労します。また、読みやすい文章を書くための様々なアイディアをいろんな人が持っています。良い文章を作るためにどんなアイディアがあるのか、いろんな人ともっと話し合いたいですね。
