「質の高い技術文書を書く方法」を読んだ
読んだ。技術記事というよりは業務での技術資料などを書くことはかなり多く、ドキュメントを書くこと自体は嫌いではないのだけれど、どうにも綺麗に整理された文書にはならず自分でも読みづらいと感じることがままあるので参考になる。
全文読んで気になったことなどをメモしておく。これまで意識できていた点、できていなかった点がそれぞれ浮かび上がったので、今後の文書作成の改善に活かしていきたい。
メモ
文書から得られるアウトプットが明確で、読み手のレベルによらず一定に伝わること
とにかく全ての情報を伝えようとして情報量が膨大になり、読み手としてどこを読めばよいのか分からないことが多いので身につまされる。
読み手のレベル感が異なることは理解できているものの、実際にはチームメンバのみに対しても「読み手のレベルによらず一定に伝わる」は実現できていないのではという感じがする。
文書から得られるアウトプットをまず定める
企画提案資料などでは目的や得られる結果について明確にすることは意識的にやっている。 一方で技術文書となると、どうしても正確性や網羅性を重視する結果ドキュメントとして目的が不明瞭なものになりがちなのかもしれない。
そもそもがモチベーションとしては情報共有であるものの、読まれることを前提にしているというよりは自分の中だけにある情報をなるべく記録しておこうという意識のほうが強いので、受け手を意識したドキュメントにならないのは当然だったかもしれない。
冒頭に記載する文書の概要・目的に、このドキュメントを読むことで読み手として何が得られるのかも記載するようにするとよいのかもしれない。
アウトプットは課題の定義から始める
これは比較的得意というか意識することが多いので書けているのではないだろうか。エンジニアリングは全ての行動が課題解決だと思っているので、ここが欠けることはないとは思う。
文書の冒頭では基本的にどのような課題を解決するのかを記載しているけれど、「読み手に欠けているこのような情報を補完する」といった視点でも課題解決を考えるべきか。
読み手を常に想像する
これは殆どできていないので今後の文書作成での大きな課題になりそう。書かれている通り読み手が複数存在しているのは理解していて、チームメンバ、マネージャ、経営層などそれぞれに対して書かれるドキュメントは異なると思っている。
いずれのケースでも伝わるように書くというのは非常に難しいが、自分が意識しているのは文書の上部では解像度が低く、後半に進むに従って解像度が高くなるという書き方をしている。結果として同じような内容を何度も記載することはあるが、経営層向けなどでは序盤のみ読めばよく、詳細を知りたい場合は読む進めれば情報を得られるという点で有用ではないかと考えている。結果として文書量が膨大になりがちという問題はある。
文書の目的を冒頭に簡潔に書く
概要、目的を文書の冒頭に記載するのは自分のフォーマットでも常に採用されている。大事。
とはいえ、後半に進むに従って関連する情報を余すところなく記そうとした結果、冒頭に記載した内容から外れていくことは多い…気がする。
アウトプット(結論)を先に書く
これは全くできていない。
日本語の慣例的な書き方という側面はもちろんあるにしろ、結論に至った経緯がないと説得力を出しづらいと感じてしまう面もあるのかもしれない。後で解決するとはいえ途中でも「何故？」と思われるのが嫌というような心境。
実際にはあまり興味がないという場合もあるし、とりあえず結論は先に書いておくというのはやってみてよいのかもしれない。
昨日取り上げたADR(Architectural Decision Records)のテンプレートではDecisionが後半に配置されていたけれど、これも先に記しておくのがよいのだろうか。
具体的な数値を文章で説明する
結論や考察を文章化するのが難しいので、どうしても数値資料をそのまま貼って読み取ってもらいたい気持ちが出てしまう。結果だけ記載していしても物足りない感じがあるけれど、参考資料として別に切り出すのが正しいのだろうなあ。
計測結果が変わった場合などに、記述が冗長だと複数箇所を更新する必要があって面倒というのもありそう。
箇条書きを濫用しない
これは苦しい。なんならほとんどの技術文書を箇条書きだけで書いているまである。
箇条書きに頼っているので文章構成力が上がらないのかという気もしてきた。
細部にまで目を配る
性格的なものあるけれど、網羅性や情報確度のほうを重視しているのでこれはなるべく気を付けている。
選択肢は可能な限り網羅する
技術選定やUI/UX検討などでは特に記録に残しておきたいと思っているけれど、ここまで記録するともはや破綻するので検討経緯だけは別資料として切り出すことが多いかもしれない。文章ではなくマインドマップのようなもので画像にするのが自分の脳内をアウトプットするには近いのではある。
自分の意見を表明する
これは話として理解できるものの、これまでの体感ではチーム内の立場などで微妙に働くこともありそうな気がしている。チームメンバに意思がない、あるいは同等の検討ができるほど知識がない場合などは特に、提示した意見に引き摺られて有用な議論ができないという懸念があってあえて記載しないようなことをしがち。
なんでも議論したがってしまう悪癖でもあるので、妥当性のある提案はそのまま通してしまってもよいしそうあるべきという気もしている。
記事冒頭にも記載はあったけれど、これは企画資料や作業手順などの文書を主な対象としているのでこれは分かるけれど、技術仕様などには私見などはあまり含める余地がないかな。
長くなりすぎない
これが一番苦手かもしれない。
解像度分割のライン見極めが難しいので全てを同一文書に含めてしまって情報が混在しがち。15〜20分という具体的なボリューム感があるのは参考になる。
まとめ
読み手が何を求めているのか、これを読んで何が得られるのかがとにかく書けていたので、今後の文書作成時には意識していきたい。
この記事がそれを実践できているかというと…技術文書ではないので許されたいか？
