虎の穴ラボ技術ブログ

虎の穴ラボ株式会社所属のエンジニアが書く技術ブログです

MENU

『エンジニアが一生困らないドキュメント作成の基本』読んでみた

技術エントリ 書評

こんにちは、虎の穴ラボ 奥谷です。

今回は、2024年9月19日に発売された『エンジニアが一生困らないドキュメント作成の基本』を紹介します。

『エンジニアが一生困らないドキュメント作成の基本』 基本情報

www.socym.co.jp

本書は、エンジニアが立ち向かうドキュメンテーションに「読み手とテーマの選定」「文章構造の設計」といった論理的なアプローチを示してくれます。
加えて、ChatGPTと如何に協業してドキュメントを作成してゆくのか？について取り上げています。

ドキュメントには、「目的」がある

ドキュメントを書くとき、何を意識して書かれるでしょうか？
本書では、ドキュメントを書くには最初に、「目的」があり、3つの分類があると説きます。

  • 説明型：概念と手順を説明する
  • 報告型：知見や活動を報告する
  • 説得型：意見や提案を伝えて相手に行動を促す

いわゆる手順書は説明型のドキュメントになり、企画提案書は説得型にあたるドキュメントになります。
それぞれの型ごとに目的があり、それを達成するためにドキュメントを作ります。

これは、書き手の目的であり、読み手も目的を持ってドキュメントを読みます。
書き手と読み手の双方の目的が達成されることがドキュメントのゴールです。
そして読み手が必要な情報を効率よく得られるようなドキュメントが「良いドキュメント」の要件の1つです。

本書は、冒頭からこのようなドキュメントの目的や良いドキュメントの定義から説いてくれます。

ドキュメントには、「骨組み」がある

本書は大体半分まで来ても、まだ「ドキュメントを書く」ことには手をつけません。
先に「アウトライン」を書くことを勧めます。

書き手にとっての指針となる章・節・項などの見出しを階層的に表現した「アウトライン」を先に書くことで、ドキュメント全体の構成を検討します。
ドキュメントの骨組みががあることで、「どこに何を書くのか」が決まり文章を書きやすくなることを挙げられています。

申請書や報告書などテンプレートがありそれに内容を埋めていくということがありますが、テンプレートはまさしくアウトラインとして効果していると、自身の業務を振り返って感じます。

「わかりやすい文章」とは

「わかりやすい文章」を本書では、「ユーザビリティの高いドキュメント」と定義します。
ユーザビリティをISO9241-11では、効率的 (efficiency)、有効さ (effectiveness)、満足度 (satisfaction)の要素を満たすものと定義されています。
ドキュメントにおいては、「効率よく理解でき」「必要な情報を得られ」「ポジティブに受け入れられる」要素を満たすことと説いています。

これを満たすため、明確な言葉を優先し、冗長な表現や修飾語は避け、情報を効率的に伝わるように配慮することが大事とされます。
いわゆる、文学的な表現や、比喩は不要というわけです。

他には、読みやすさのために、読み手の視点でかくことなどを説いています。

ChatGPTとの協業

本書の後半で全体の約2割を割いて「ChatGPTと協業して、効率よく書く」ことを取り上げています。
昨今の潮流から、ChatGPTを使って業務の改善や効率化取り組みが進んでいますが、本書では「CahGPTにおまかせ」するのではなく「ChaGPTに支えてもらう」というスタンスを取ります。
それは、ハルシネーションの結果、もっともらしいことを答えてくる現実があるためです。
この欠点を補うために、

  • ドキュメントで伝えたいことをまとめ、ChatGPTに伝える
  • ChatGPTの出力を下書きとして扱い、自分で手直しする

という使い方を推奨します。

このような使い方を推奨し、ChatGPTの生成物をそのまま使わないという方針があるからこそ、先に挙げたアウトラインの作成などドキュメンテーションの基礎の技を活かすことができます。 本書では、「ChatGPTに仕様書の構成を考えさせる」という具体例の中で、 考えさせた構成案を、先に養った観点で評価して書き換えするという工程の流れを示してくれます。

まとめと振り返り

本書は、「エンジニアが一生困らないドキュメント作成の基本」と銘打つだけあり、エンジニアが立ち向かうドキュメンテーションにフォーカスされた内容になっています。
ドキュメントも設計や構造が大事であるという観点は、エンジニアには受け入れられやすいのではないでしょうか？

本書では、「ドキュメントの階層構造を理解すると、要点を掴みながら読める」と説いています。
その意識を持ちインプットを心がけましたが、確かにそういった読み方がしやすい本にもなっており、本書自体が書いてあることが達成されているドキュメントとして完成されていると感じられました。

「ドキュメントを書いてください」というのはある種のオープンクエスチョンだと思います。
これを「アウトラインを書く」「構造を検討する」ことで、個別具体のパラグラフは何を書くのかが定まったクローズクエスチョンへの落とし込みを行うことで、「書くのは苦手」はかなり軽減されるのではないでしょうか？

その昔求められた読書感想文などは、苦手だなという記憶ばかり思い出されますが、作る文章の全体像に対して「起承転結を意識せよ」くらいしか教えてくれなかったしなぁと今振り返ると思う限りでした。

これまでの文章作成の苦手体験の過去を振り切って、ドキュメントを書こうとする方にお勧めできる一冊だと感じます。
また、これから春にかけて新卒の方に渡す一冊にもいいかもしれません。

Fantia開発採用情報

虎の穴ラボでは現在、一緒にFantiaを開発していく仲間を積極募集中です！
多くのユーザーに使っていただけるtoCサービスの開発をやってみたい方は、ぜひ弊社の採用情報をご覧ください。
toranoana-lab.co.jp