エンジニアの仕様書や企画書にも使える！論理的で分かりやすいドキュメント作成のコツを徹底解説

元々はサイボウズのエンジニアでしたが、パートナー企業向けに書いた技術資料が「分かりやすい」と評価を頂き、技術資料の制作を専門に行う部署に異動しました。そこでテクニカルライターとして製品マニュアルやリリースノートなどを書くようになり、現在はSmartHRの開発部門でUXライターとして活動しています。

テクニカルライターはエンジニアが書いた要件定義や仕様書を元に、社外ユーザー向けにライティングを行っていきます。なので、エンジニアがいかに要件定義や仕様書をわかりやすく書けるのかは、私たちにとっても重要です。

エンジニアには情報発信の文化があり、技術ブログや書籍などを書いたことがあるエンジニアも多いと思います。しかし、ドキュメントに苦手意識を持っている人が多く、書き方を体系的に学んだことのあるエンジニアはほとんどいません。そこで前職でエンジニア向けのテクニカルライティングの社内講習を実施し、社外にも資料を展開したことがあったのですが、予想以上の反響がありました。「もっと体系立ててドキュメント作成の基本を伝えられたら」と思い、本書を執筆しました。

理想と現実のギャップを感じるものの何が課題なのか分かっていない人が多いと思います。社内の過去ドキュメントやテンプレに従って書いているものの、上手く書けないという方をよくお見掛けします。

基本的に共通していることが多いと思います。エンジニア以外の方もビジネスシーンで報告書や企画書を書く機会があると思いますが、あらゆる場面で「ドキュメント作成の基本」は活用できると思います。

テクニカルドキュメントは小説などと違って、情報を伝えるという目的を達成することが求められます。つまり、実用性（ユーザビリティ）のあるドキュメントが「良いドキュメント」です。本書では、 ISOのユーザビリティーをもとにその実用性には以下の3つの要素があると定義しています。

そうかもしれませんが、実用性をかなえるためには重要なポイントです。ドキュメントを隅から隅まで読まないと欲しい情報が得られないのではなく、欲しい情報を効率よく得られるドキュメントでなければなりません。

製品やプロダクトには不具合や障害の可能性、データの上限等の制限事項などユーザーにとってネガティブな情報もあります。ただ、それらの情報を「これは出来ない」「あれも出来ない」と過剰に伝えてしまうと、製品全体の満足度も下がってしまいます。ネガティブな情報をいかにポジティブに伝えるかが重要です。

これは私自身の経験からも、身近なテクニカルライターの話からも感じることです。実際にエンジニアからテクニカルライターに転身し、活躍している人も多いです。プログラミングを書くときに自然と意識していることをドキュメントでも意識すれば、そこまで苦手意識を持たずに書くことができると思います。

共通点は以下の4つです。

ドキュメントが苦手という方は、情報を整理しないまま、いきなりドキュメントに落とし込んでしまうケースが多いです。しかし、プログラミングではいきなりコードを書くことはしないですよね。多くの場合、最初に設計というフェーズがあると思います。ドキュメントにおいても、構成（アウトライン）の設計が重要です。

さらに「2．内容を表した関数名を付ける」ということを説明すると、関数名はドキュメントで見出しにあたります。処理内容を想像しやすい関数名をつけるのと同じように、書かれている内容が端的に分かりやすい見出しを付けます。

「3．1つの関数に1つの役割を持たせる」というのは、ドキュメントでは「1つの見出しに1つのテーマを持たせる」と言い換えられます。1つの関数が複数の役割を持つと、プログラムの読みやすさやメンテナンス性が低下しますよね。ドキュメントでも、1つの見出しの中に複数のテーマを詰め込むと、言いたいことが見えなくなり、わかりやすさが低下します。

「4．コードを共通化する」ということは、ドキュメントでは「記述を共通化する」、つまり同じことを複数の箇所に書かないということです。特にマニュアルでは同じ記述をいくつもの箇所に書くことになりがちですが、共通する記述を1箇所にまとめ、参照リンクを貼ることで、時間や労力を節約できるだけでなく、記述の修正も楽になります。

まず、「説明型」のドキュメントは、マニュアルや仕様書、要件定義書など、仕様や使い方を説明することを目的としています。このドキュメントの特徴としては、情報がどんどん増えていってしまいがちである一方で、必要な情報は読む人によって違うということです。そのため、どこに何が書かれているかをいかに一目瞭然にするのかが課題となります。

ええ。それ以外にも技術ブログや調査報告、論文なども報告型に含まれます。説明型のドキュメントに比べると少ない文章量になることが多いと思いますが、とにかく素早く情報を得られるということが求められます。読み手は報告書を流し読みし、3割程度しか読んでくれません。書き手もそれを前提に、要点を先に伝えていく必要があると思います。

企画書や提案書などが「説得型」にあたります。他にも、開発チームに新しいツールを入れたい場合、自分の判断だけで入れるわけにはいかないので、関係者に説得する必要がありますよね。人を説得して動かすという機会はエンジニアの日常でも意外に多いと思います。そこで大事なのは、関係者がきちんと納得できる論理になっているかということです。なぜその企画やツールが必要なのか、何をやりたくて、何を目指しているのか。論理が整った文章であるかどうかが求められます。

やはりエンジニアが執筆する機会が多い「説明型」だと思います。量が膨大になりがちなので、どこに何が書いてあるのかわからなくなることが多いようです。それを防ぐためには、見出しを工夫しましょう。見出しだけで何が書いてあるのか、すぐに理解できるようにすることが重要です。

ドキュメントにするテーマを、「why（なぜ）」「what（何を）」「how（どのように）」の3つの要素で分解することをおすすめしています。これらの要素は、「目的」「目標」「手段」と置き換えることもできます。

たとえばソフトウェア製品のマニュアルを書く場合、次のように分解できます。

まずは箇条書きで構わないので、情報を上記のような3つの要素に分解し、構成として落とし込みます。プロダクトの機能が複数あれば、それらを一つずつ分解していくイメージです。

テーマを分解できたら、その内容をもとにして見出しの構成を組んでいきます。次のように、「why（なぜ）」「what（何を）」「how（どのように）」をさらに分解してみましょう。

まず、見出しの情報には「順列」と「並列」、2種類の関係があり、この関係によって並べ方が変わります。「順列」というのは「ある情報の理解のためには前提としてこの知識が必要」といった順序関係がある情報のことを指します。プログラマーはライブラリの依存関係を想像してもらえると分かりやすいです。

設計作業手順書やマニュアルなどですね。これらのドキュメントでは、「機能」を伝える前に「機能の利用目的」を書かれても、ユーザーはまだ「機能」について理解できておらず、目的をしっかり理解することができません。そのため、「まずこの情報を伝えないと意味が伝わらない」と考えられる内容を優先的に提示します。

また、説明に時系列での順序がある場合は、時系列に沿って要素を並べます。プロダクトの操作説明を行うドキュメントの場合、「チャットルームを作成する機能」「管理者がルームを削除する機能」「管理者が参加者を管理する機能」…と並べてしまうと、まずチャットルームに参加する方法が分からないのに、いきなり管理方法について書かれても理解できなくなってしまいます。「チャットルームに参加する機能」から始まり、「チャットルームを作成する」「管理者が参加者を管理する」と利用者の時系列に沿って段階的に説明していくことで、読み手はプロダクトを操作しながら効率良く使い方を学べます。

ドキュメントは一部しか読んでもらえないという前提に則り、ニーズが高く優先度の高い情報を先に伝えていきます。たとえば「地域コミュニティの形成」「イベントや活動の計画」「趣味や興味の共有」の3つの項目には、順序関係はありません。どの内容から話しても内容を理解することができるからです。ただ聞き手が興味を持ってくれやすいよう、「趣味や興味の共有」「地域コミュニティの形成」「イベントや活動の計画」と並べ替えると、聞き手も必要な情報を効率よく得ることができます。

慣れが必要な部分も大きいと思います。ただ、やみくもに書いても上達しにくいので、うまく書くコツをお伝えしますね。

1つ目は、「1つのパラグラフで言いたいことは1つに絞る」ということです。ドキュメントに限らず、プレゼンテーションの資料でも1つのスライドでは言いたいことを1つに絞るというのはよく言われるともいます。1つのパラグラフに複数の主張を詰め込むと、何が言いたいのか理解しにくく、ぼやけてしまいます。ですから、1つに絞るというのが重要です。

2つ目のポイントは、パラグラフが順番に頭に入っていくことで、全体の納得を得られるように、「各パラグラフに論理的な繋がりを持たせる」ということです。

ええ、なのでまずは各パラグラフの中で言いたいことだけをキーワードとして抜き出し、箇条書きで良いのでリスト化していきます。それだけを読んでみて、論理的な流れになっているか、キーワードだけを読んでも伝わるかを確認してから、詳しい説明を書き加えていきます。そうすることで、流れの良い文章に仕立てていくことができます。

パラグラフには、言いたいことを表した中心文（トピックセンテンス）、それを支える具体例などの支持文（サポートセンテンス）、言いたいことを印象付ける結論文（コンクルーリングセンテンス）があります。まとめというのは結論文にあたると思います。必須ではありませんが、入れることによって内容を印象付けられますし、より理解しやすくなると思います。

ええ、私もよくメモをします。メモの仕方として、階層を意識すると良いと思います。情報をただ羅列するのではなく、情報の親子関係を見つけていくと、情報が整理されますし、それを階層化した上でドキュメントすることでこれまでお伝えしてきた既知から未知・時系列での順列もしやすいです。

そうですね。ドキュメントを書くというのは、頭の中の情報を整理する機会にも繋がると思います。なぜそれをやるのかという目的や、何を目指すのかというゴールを整理すると、話し方においても理路整然と話すことができるようになるので、コミュニケーションも取りやすくなるのではないかと思います。

エンジニアによくある具体例を交えて書いてあります。また、ドキュメントの書き方をステップバイステップで解説し、この順に沿って書けば良いドキュメントが書けるよう、手順を説明しているのが本書の一番の特徴となっています。さらに生成AIの活用についても取り上げてあります。生成AIはプログラミングにおいても、良いコードであるかを評価してかなければ活用していくことはできません。同様に、良いドキュメントとは何かを理解し、評価できるようになることで、ドキュメント作成においても生成AIを活用しやすくなると思います。ぜひ本書を参考にしてみてください。