ちょき☆ぱたん　お気に入り紹介　(chokipatan.com)

第１部　本

エンジニアが一生困らない ドキュメント作成の基本（仲田尚央）

『エンジニアが一生困らない ドキュメント作成の基本』2024/9/19
仲田 尚央 (著)

（感想）
　日本語ドキュメントのスペシャリストであるテクニカルライターの仲田さんが、エンジニアが「いつ」「何のドキュメントを」「どうやって」書けばよいのかを、分かりやすく解説してくれる本で、主な内容は次の通りです。
＜基礎編＞
Chapter１　良いドキュメントを効率良く書くために
Chapter２　ドキュメントの読み方を理解する
Chapter３　読み手とテーマを選定する
Chapter４　テーマを分解する
Chapter５　ドキュメントの骨組みを組む
Chapter６　文章を書く
Chapter７　わかりやすい文を書く
Chapter１～７までの振り返り
Chapter８　ChatGPTで効率よく書く
＜実践編＞
Chapter９　ドキュメントの構成例
　　　＊
　ドキュメント嫌いのエンジニアは多いと思いますが、エンジニアにも仕様書や報告書、さらには使用手引書などドキュメントの仕事はたくさんあります。この本は、ドキュメントが苦手な人でも、それなりに書けるようになる具体的な方法を教えてくれます。
「Chapter１　良いドキュメントを効率良く書くために」には、良いドキュメントについて……
「（前略）「良いドキュメント」は、「必要な情報を正しく得られること」、「効率良く理解できること」、「不快さがなく、ポジティブに受け止められること」の３つの要素を持つものと定義できます。」
　……ということを教えてくれるだけでなく、次のようなコツも教えてくれました。
・「（前略）書き手としては、流し読みされることを前提に、それでも必要な情報が伝わるように書く努力が必要です。」
・最も大事なことは、「要点を先に伝える」こと
・必要な情報だけを書く
　　　＊
　またエンジニアにとっては馴染みの高いプログラミングと書くことの共通要素として……
１）最初の設計が大切
２）内容を表した関数名（見出し）を付ける
３）１つの関数に１つの役割を持たせる＝１つの見出しに１つのテーマを持たせる
４）コードを共通化する（同じことを複数の箇所に書かない）
　……があると教えてくれるのも、分かりやすいと感じました。
　私自身の実感としては、「ドキュメントの種類ごとのテンプレートを使う」というのがドキュメントを作るときの一番の早道だと思いますが……（笑）。
　個人的に最も参考になったのが、Chapter５と７。まず「Chapter５　ドキュメントの骨組みを組む」では……
・「（前略）ドキュメントにおけるアウトラインとは、章・節・項などの見出しを階層的に表示したものを言います。」
・「（前略）うまく書けないところは後回しにして、書けるところから先に書くことで、知識や考えた整理されて、書けなかったところも書けるようになることがよくあります。」
　……などの他、分類したテーマをアウトラインに仕立てるステップとして……
１）要素を並べ替える
２）見出しを付ける要素を選ぶ
３）見出しを決める
４）見出しだけ読んでみる
　……という手順の紹介もありました。また「Chapter７　わかりやすい文を書く」では、文章を書くときに意識するポイントとして……
１）重要なことから書く
２）読み手の視点で書く
３）能動態と受動態を使い分ける
４）簡潔に書く
５）読点や箇条書きで並列関係をはっきりさせる
　……という５点があることを教えてくれます（もちろん本書では詳しい説明があります）。
　そして「Chapter８　ChatGPTで効率よく書く」では、なんと生成AIを利用したドキュメントの作り方まで教えてくれるのです（笑）。
ChatGPTの使い方のコツ（欠点を補う対策）としては……
１）ドキュメントで伝えたいことをまとめて、ChatGPTに伝える
２）ChatGPTの出力はあくまで下書きとして扱い、自分で手直しする
　……だそうです。
　なお、「ChatGPTに下書きを依頼するときは、間違った情報が盛り込まれる可能性に注意が必要」です！　ChatGPTはとにかく「それらしい文章」を出すのが得意なので、一見すると真実（事実）を書いているように見えますが、何が「正しい」のかを知っているわけではなく、なんと「計算さえ正しくない」ことすらあるので、本当に注意が必要です。
　それでもChatGPTは、いろいろな分野での「標準のフォーマット」を知っていることが多いので、エンジニアにとっては、とても便利に使えるものだと思います。
　また本書ではChatGPTが文章の校正にも利用できることを、事例をまじえて紹介してくれるので、それもとても参考になりました。例えば次のように指示するそうです。
「次の文章の誤字や脱字を修正してください。修正した文字は太字にしてください。」
　……なるほど！　修正した文字は太字にしてもらうと、確かに修正箇所が一目でわかって便利ですね！　ChatGPTに校正してもらえると、「うっかり読み流してしまうようなミス」を防げそうな気がします。ただしこの修正自体が間違っている可能性もあるので、この修正部分も含めて「正しさ」の確認が必要ですが……。
　そして「Chapter９　ドキュメントの構成例」には、次の４つのドキュメントの構成例が紹介されていました。これらはエンジニアにとって、よく書く必要があるものなので、とても参考になると思います。
9－1　要件定義書
9－2　仕様書
9－3　ユーザーマニュアル
9－4　報告書
『エンジニアが一生困らない ドキュメント作成の基本』……まさにタイトル通りの本で、特にドキュメント嫌いのエンジニアの方にとって、とても役に立つと思います。ぜひ読んでみてください☆
　　　＊　　　＊　　　＊
　なお社会や科学、IT関連の本は変化のスピードが速いので、購入する場合は、対象の本が最新版であることを確認してください。

Amazon商品リンク

興味のある方は、ここをクリックしてAmazonで実際の商品をご覧ください。