本記事の著者
株式会社ソラコム テクニカルライター 矢崎 誠
SORACOMのドキュメントをメンテナンスしたり、生成AIを利用するSORACOM Support Botを開発したりしているテクニカルライター。アベイズム株式会社→有限会社ビートラスト（フリーランス）→LINE株式会社→株式会社ソラコムと何度か転職はしていますが、社会人になって約25年間、常にテクニカルライターです。最近は生成AIに面白さを感じて開発成分増量中。「LINE社内で大評判のテクニカルライティング講座で説明した内容をあらためてブログにまとめてみた」の著者。
はじめに
私は、株式会社ソラコム（以下、社名を「ソラコム」と表記します）で、テクニカルライターとして働いている矢崎です。ソラコムのテクニカルライターは、自分でドキュメントを整備することはもちろん、ソラコムのメンバーがドキュメントを整備することも手伝っています。
この連載では「超時短テクニカルライティング」と称して、私がドキュメントを作成するときのアイディアをいくつか紹介します。普段、IT製品のマニュアルや仕様書などのドキュメントを作成している人はもちろん、それ以外のドキュメントを作成するときにも役立つ内容です。ぜひ最後まで手を動かしながら読んでいただけると幸いです。
対象読者
本連載の対象読者は、仕事でドキュメントを書くことがあるエンジニアです。ドキュメントを書かないエンジニアはいらっしゃらないと思いますので、ほぼすべてのエンジニアが対象になると思います。また、第1回の記事を読んでいただいていることを期待しています。まだの方はぜひ読んでいただけると嬉しいです。
構成を考えることの重要性とは
ドキュメントの構成を検討することは、読者にとって価値がある情報を理解しやすく届けるうえで極めて重要な作業です。「構成」とは、文章をどの順序で並べるか、どの程度詳細に説明するかなどを決定する作業です。構成が深く考えられていないと、一つのドキュメントで同じ説明を繰り返すことになったり、論点が飛び飛びになって話の流れが理解しにくくなったりします。
例えば、「あ」～「え」の順番で理解しやすいドキュメントがあった場合、構成が深く考えられていて「あ」「い」「う」「え」の順番で情報が並んでいれば、読みやすいドキュメントになるでしょう。
一方で、「い」「あ」「え」「う」の順番に情報を並べてしまうと、一つのドキュメント内で行ったり来たりが発生してしまうかもしれません。
しかし多くの人にとって、普段の文章で構成を意識することは、あまり無いでしょう。そこでこの記事では、「ドキュメントの構成を考えるうえで役立つプロンプト」を紹介します。テクニカルライターとして働く私の思考をトレースするために便利なプロンプトともいえると思います。ぜひお試しください！
ドキュメントの構成を考えることで得られる効果
「ドキュメントの構成を考える」プロセスを通じて次のような効果が得られます。
- 読者の理解を促進：対象読者の知識レベルに応じて情報を整理することで、わかりやすい説明（読者によるスムーズな理解）が期待できます。
- 読者体験の向上：情報を適切な順序で配置することで、読者が必要な情報を容易に見つけられるようになります。つまり、拾い読みがしやすいドキュメントになります。
- 情報の漏れ防止：情報を並べる際に、説明が不足している箇所に気付けます。
構成とは？
ドキュメントを書くときに「構成」がつく作業には「1ページの構成」と「複数ページの構成（目次構成）」があります。ここでは「1ページの構成」を取り上げます。つまり、あるページの先頭に何を書いて、続けて何を書いて、最後に何を書くかという、「ドキュメントの流れ」を検討する方法を説明します。
ここでは説明しませんが「複数ページの構成（目次構成）」が表すのは、ドキュメント全体でどのような順序で情報を並べるか、ということです。この記事ではドキュメント全体まで拡張せずに、「1ページの構成」を検討する方法を説明します。
