システム管理者のためのBookCafe

Vol.137　エンジニアが一生困らない ドキュメント作成の基本

概要

書籍のインク独特の香りを感じながら、出会ったことのない世界、新たな発見、体験してみませんか？

目次
内容紹介
Satoshi’s Review

私はドキュメント作成が嫌いです。
恐らく、文を書くのが好きでたまらないという方はエンジニアには少ないと思います。
しかし、実際の開発業務では多くのドキュメント作成をすることが求められます。
その度に、より少し分かりやすく、より簡単にドキュメントを作成できないものかと悩んでいました。
「ドキュメント作成の為のドキュメントがあれば…」と思っていたところ、本書を見つけ思わず手に取りました。
ドキュメント作成で同じような悩みをお持ちの方、また若手のエンジニアの方におすすめの本です。
また、生成AIのChatGPTをドキュメント作成に活用方も紹介しています。

内容紹介

 
エンジニアが一生困らない ドキュメント作成の基本
仲田　尚央
「コードを書くのは好きだけどドキュメントは苦手」
「ドキュメントはつい後回しにしてしまう」
エンジニアの皆さん、そんな覚えはありませんか？
本書は、日本語ドキュメントのスペシャリストであるテクニカルライターの著者が、エンジニアが「いつ」「何のドキュメントを」「どうやって」書けばよいのかを、イチから解説します。
先生役の著者と生徒役をキャラクターにし、全編にわたってイラストを豊富に掲載。
はじめてドキュメントを書くエンジニア、またはこれまで自己流で書いてきたエンジニアが、一度読めば一生使える知識満載です。
装丁画と挿絵は、カケヒジュンさんが手がけます。
（ソシム 紹介ページ）

 

Satoshi’s Review

私が読んで印象に残った部分を、ポイントごとに紹介します。

◆まずドキュメントの読み方から
本書では、最初にドキュメントの読み方から解説しています。
ドキュメントの階層構造を理解することで、効率的に情報を得ることができます。
また、自分が書き手になった時にも、どういったことを意識すべきかが分かってきます。

◆読み手とテーマの選定
ドキュメントを書く上で重要なこととして、目的を明確にすることが大事です。
「誰に(読み手)」「何を(テーマ)」を決めることで、専門用語をどう使うか、用語に解説を入れるかなどを決めることができます。

以下の要素で読み手のレベルを絞り込みます。
・読み手の知識レベル(初心者向け、上級者向け、など)
・読み手の目的(トラブルの解決方法を知りたい、製品の使い方を知りたい、など)
・読み手の立場や役割(一般ユーザー、開発者、など)
これらを最初に決めることで、自然とテーマも決めやすくなります。

◆ドキュメントのアウトラインの作り方
アウトラインとは、骨組みを意味します。ドキュメントにおいては、章・節・項のような見出しを段階的に表示したものを言います。
見出しを決めることで、書き手・読み手の両方にメリットがあります。

◆書き手へのメリット
・ドキュメント全体の大きな論理の流れを整理できる
・どこに何を書けばよいのか分かり、文章を書きやすくなる

◆読み手へのメリット
・目次があることで、必要な情報をすぐに探せる
・ドキュメントの要点を掴むことができる

◆わかりやすい文章の作り方
パラグラフ(話のまとまり)ごとに伝えたいことをはっきりさせて書くと、わかりやすい文章になります。また、伝えたいことはパラグラフの冒頭に書くべきです。　
その後で、言いたいことの理由や説明を述べることで、まとまりのある文章になります。

さらにわかりやすい文章を書くためのテクニックがいくつか紹介されています。
・なるべく肯定形で書く(禁止事項は否定形で書く)
例:
☓アプリのアップデートは放置したままにしないでください
◯アプリのアップデートはなるべく早めに適用してください

◆できるだけ具体的に書く
例:
☓スマートフォンの音量の設定を確認してください
◯スマートフォンが消音の設定になっていないことを確認してください

◆まとめ
ドキュメントの書き方を解説している本だけあって、分かりやすい文章と実例を用いており、非常に役立ちました。
この本を読んで、苦手意識があったドキュメント作成に対して、前向きになれました。
私と同じようにドキュメント作成についてお悩みの方が居れば、ぜひ本書を手にとっていただければと思います。

 

連載一覧

コメント

筆者紹介

“システム管理者のためのBookCafe” レビュアーのご紹介
●システム管理者の会 推進メンバー
システム管理者の会の企画・運営をする推進メンバ―が、会員の皆様にお奨めする本をご紹介してまいります。

この本を読んだことがある方、読まれた方のご感想もお待ちしております！（⇒ぜひ、コメント欄にコメントをお寄せください☆）

バックナンバー