こちらのイベントに参加してきたので、会の様子と感想を書いていこうと思います。
会の概要
以下、イベントページから引用です。
「コードを書くのは好きだけどドキュメントに起こすのは苦手」というようなエンジニアの方も少なくないのではないでしょうか。 ドキュメントを速く、正確に、わかりやすく書くための方法をイチから解説している本書について著者である仲田 尚央 氏にポイントを解説していただきます。
会の様子
仲田さんの講演
本書の核
複雑な情報を適切な構成を作ってドキュメントの形に落とし込んでいく技術が核になっているという話がありました。
ドキュメントの種類と目的
ドキュメントの大まかな種類とそれらの目的に関する話がありました。以下のように大まかには分けられるということです。
- 要件定義書, バックログ, 仕様書, マニュアル, 作業手順書...概念や手順を説明する
- 報告書, 論文, 技術ブログ...知見や活動を報告する
- 企画書, 提案書...相手に行動を促す
これらの目的は読み手も書き手の両方の視点で効率よく達成する必要があるということでした。
ドキュメントを書くうえでの課題
- ドキュメントに書くべきことはなんとなく頭にあるけど文章がかけない
- 何からどうやって書けばいいのかわからない
- とりあえず書き出したけど話が繋がらない
といった点がドキュメントを書くうえでよくある課題だという話がありました。これらは、「いきなり文章を書き出してしまう」という点で共通しているそうで、ドキュメントに関しても設定が重要だということです。
ドキュメントの特徴
ドキュメントには、
- 何らかの目的が達成されることが求められる
- 情報が正しく伝わる必要がある
- 情報が効率よく伝わる必要がある(どこに何が書いてあるかが一目で伝わらないといけない)
という特徴があるという話がありました。
ドキュメントには、ユーザービリティの要素であるEffectivness/Efficiency/Satisfactionを満たすような情報整理/構成/文の要素があるため、それらが上記の特徴を満たすようにする必要があるということです。
情報整理
大きく複雑な情報は人に伝わらないため、階層構造を使って複雑な情報を分解する必要があるということです。
情報分解する際は、Why, What, Howを使って分解することが一つの方法としてあり得るということですが、情報がかなり複雑な場合はさらに分解する必要があり、その際は構成要素での分解や具体例での分解の2パターンがあるということでした。
これらの分解パターンは、読み手がどういう目的で読むドキュメントなのか？というところから考えるということです。
アウトライン
ドキュメントには、構成を読み手が一目でわかるようにしながら書き手が何を書くのかを組み立てやすくするためのアウトラインが重要だということでした。
アウトラインは書き手にとって、
- 論理を構成する
- どこになにを書くのかが決まる
という役割があり、読み手にとっては、
- 必要な情報を探す手がかり
- 要点を掴む手がかりになる
という役割があるという話がありました。アウトラインを仕立てる際には、
- 要素の並べ替え(既知から未知, 時系列, ニーズの大きさ...)
- 見出しを付ける要素の選択(内容が多い要素や重要な要素に見出しを作る)
- 見出しを決める(本文に沿った内容になるように調整する)
- 見出しだけを読む
という順序がおすすめだということです。
文章の構成
見出しの中にも複数のテーマがあるため、話題(言いたいこと)をパラグラフにまとめて、それを見出しに結びつけることが重要だということでした。
パラグラフを作ることで書くべきことが小さくなりながら話の流れを作りやすくなるため、文章が展開しやすくなるということです。
パラグラフを展開する際には、
- 理由の展開
- 説明を述べる
- 具体例の記述
という3パターンがあるということでした。
文章を効率よく書くステップ
文章を書く際には、
- 各パラグラフで言いたいことを一文くらいで書く
- 話の流れを確認する
- 言いたいことの理由や説明を加える
というステップで書くのがおすすめだということでした。
Q&A
セッションの後はQ&Aがありました。以下、質問と回答を一問一答形式かつ常体で記載していきます。
継続的にメンテナンスするのが大変。いい方法はあるか？
仲田さんは仕事だからやってしまっているところはあるが、「なぜ」がブレないようなドキュメントにしたほうが良い。あとは画像はなるべく使わないようにするとか、どこに何かが書かれているかをわかりやすくしておく。
あとは開発のプロセスに明示的に組み込む(Doneの定義にいれるなど)
他人から見て何が必要なのかがわからないのだがやることは？
仕様書を書くときは、あまり情報がない状態でプロダクトを実際に触ってみるようにしている。あとはユーザーと直に接する。
複数名でドキュメンテーションするときに書き方を揃える工夫は？
ガイドラインを作る。(日本語スタイルガイドとかを使う)あとはLinterを使ったりしている。
レビューの秘訣は？
段階を挟むようにしている。まずは見出しだけレビューを挟んでその後文章のレビューをするなど。
また、できているところもしっかりと伝えるようにしたり、Nice to haveなのかMustなのかどうかを記載したりしている。
社内向けか社外向けかで意識が変わることはあるか？
基本的には同じ。
社内であれば、フロー情報とストック情報を明示的に分けたりはしている。
パラグラフのパターンはどれを選ぶのか？
言いたいことから自然と決まることが多い。
文章を短く簡潔にまとめた後に文章のぶつ切り感が気になってしまうのだが良い対策はあるか？
接続詞を意識的にいれる。
会全体を通した感想
内容の納得感や発表の構成が見事で、まさにドキュメント作成の考え方が適用されているんだなというのを実感する発表でした。
質問では、これまでに見たことがない数の投票がドキュメントのメンテナンスに関する問題に入っていて、みんなのドキュメントに関する悩みの大きな要因になっているんだなあというのを実感しました。
