はじめに・背景
はじめに、私は２年目のエンジニアです。業務を通じてドキュメントを書く機会が非常に多いです。ドキュメントを書くのが苦手で、この機会にテクニカルライティングに関する著書を読みました。そこで得た学びや業務を通じて得た学びを残しておこうと思います。
テクニカルライティングとは、技術的な情報を特定の聴衆に対して明確かつ簡潔に伝えるための専門的な書き方のことです。
対象者
本記事の対象者は、若手のエンジニアやドキュメントを書くことに苦手意識を持っている方です。もちろん私の備忘録も兼ねています。（笑）
目的
目的：ドキュメントを書くことへの苦手意識を減らすこと
1つの記事を読んだだけでドキュメントの記述が劇的に変わるわけではないと思います。ただ、意識しながら書くことで誤字脱字が減ったり、書くことに慣れたりすると思いますので上記を目的としています。
要約
今回の記事を読むのが面倒な人に要約を以下にリストで示します。
- 読み手が誰なのか決める
- ドキュメントの目的を決める
- 全体構成を考えてから書き始める
- リソースをかけすぎない
- 言葉・表記に統一性を出す
- わかりやすい見出しを意識する
- 一文一義で書く
- 具体的な表現を意識する
ドキュメントを書き始めるにあたっての準備
この章では、ドキュメントを書き始めるための準備について記述します。
皆さんはドキュメントを書く必要が出てきた時に、いきなり書き出していないですか？
文章を書き出すタイミングというのは、頭の中で整理がついていないことが多いと思います。理由は、ドキュメントというのは、誰かしらに伝えるためのものだからです。すでに皆が知っていることを改めてドキュメントに残すというよりは、知らない人のためにドキュメント化する、シーンが多いはずです。
そこで、本章ではわかりやすいドキュメントを書くための準備について紹介します。
読み手の選定・目的の明確化
ドキュメント化する上で最も重要なことは、読み手の選定です。読み手の選定とは、読み手の知識レベルや、知りたい事を明確にします。読み手が前提知識を持っていないのに、専門用語を使っていてはどんなにわかりやすくても伝わらないです。
読み手の選定が終われば、ドキュメントの目的を明確にします。目的のないドキュメントは存在しないと思っています。大なり小なり目的があって書いているはずなので、最初の段階で明確にしておきましょう。
私は以下のように読み手の選定と目的の明確化をしています。
Who : ユーザ
前提知識 : あまりない
目的 : エラー発生時の対処方法
背景を考える
読み手の選定・目的の明確化ができたら、背景を考えましょう。読み手がなぜそのドキュメントを読む必要があるのかを背景を通して伝えましょう。個人的にこのパートが一番難しいと思います。なぜなら、ドキュメントを書く際にどういう事情で書いて欲しいかということを伝えられないケースが多いからです。その場合は、依頼者にきちんと確認することをお勧めします。
ここまでで、ドキュメントの最初の流れはできてきたかと思います。
ドキュメントの全体構成を考える
背景までできれば、いよいよ内容に取り掛かかります。内容を記述する前にも工夫が必要で、何を書くか？ということを最初に明確にしておきます。要は章立てを先に考えようということです。
目的をルートにして、そこからサブテーマ、サブテーマを説明するためのパラグラフといった感じで構成を考えると良いです。
例えば、スマートフォンの操作方法に関するドキュメントだった場合は以下のように構成を考えます。
スマートフォンの操作方法
・カメラ機能の使い方
・拡大、縮小の設定の仕方
・ポートレート機能の使い方
...
・電話機能の使い方
・アドレス帳登録の仕方
...
いきなり、スマートフォンの使い方を説明するより、構成を考えてからの方が書きやすいのがわかると思います。下流に行くにつれてテーマに具体性を持たせましょう。紙に書気出すでもいいですし、ドキュメントにアウトラインとして設定するでもいいと思います。
ドキュメントにかけるリソースを考える
全体構成ができたら、書き出して良いです。ただ、あくまで私の考えですが、書き出す前にそのドキュメントに割ける時間を決めておくと良いと思います。1週間かけても1日かけても完成する質が高くなるわけではないので、締切は決めておくと良いです。
統一性のあるドキュメントの作り方
本章では、統一性のあるドキュメントを作成する方法について記述します。統一性のあるドキュメントとは、読みやすかったり、主張が明確なドキュメントです。
言葉・表記の統一
ドキュメント内に出てくる単語に統一性を持たせましょう。
例えば、スマートフォンの操作に関するドキュメントなのに、スマートフォンと記述したり、デバイスと記述したり、iPhoneと記述したりすると、読み手は何の説明なのかわからないです。なるべく、ドキュメント内で一つの表現にしましょう。
また、ドキュメントの初めの方に言葉の定義をまとめておくのも良いでしょう。読み手が理解できない単語が出てくるたび説明を入れると、検索性が低いです。なので、どこかに定義をまとめておくと良いでしょう。
わかりやすい見出しを意識する
本文の内容が伝わるような見出しを意識しましょう。読み手が知りたい情報がどこにあるのかわかりやすくするなります。皆さんも経験があると思いますが、Qiitaなどの記事を読む時、全ては読まないですよね。知りたい情報をctl + Fで検索しますよね。
一文一義
基本的に一文一義を意識しましょう。文章を書いていると、伝えたいことがたくさんあってついつい文が長くなります。文が長いと、きちんと頭を使って読まないといけないです。なるべく1文に1つの意味をこめるようにしましょう。好みもあると思いますが。。。
具体的な表現を意識する
ドキュメント内の文章は具体的に書きましょう。曖昧な表現だと、読み手は結局何をしたらいいの？となってしまいます。理由は、読み手は必要な情報を求めてドキュメントを読むので、なるべく言い切って欲しいためです。責任を持ちたくないので、曖昧な表現になることは多いですが。。。
よりよりドキュメントにするための工夫
本章では、ドキュメントの改善方法を記述します。一旦ドキュメントを書き終えた人が取るべき行動を記述します。どんなに意識しても読み手は他人なので100%伝わり切ることはないです。内容の指摘も絶対に発生します。そこは割り切りましょう。
全体の分量を考える
ドキュメント全体を振り返って、分量が多くないか確認しましょう。良いドキュメントは、分量が少なく知りたいことが豊富な場合が多いです。なので、ドキュメントの文章を見て、削れる場合は削りましょう。ただ、手順書などの場合、細かい操作まで記載されている方が嬉しい場合もあります。そこは読み手を意識して判断しましょう。
残縁なことに読み手はドキュメントの2~3割程度しか見てくれません。私も読み手の場合は基本的にそうですから仕方ないですが。。。
レビューをもらう
どれだけ自分で見返しても気づける誤りは限られています。フラットな状態でレビューしてくれる人に確認してもらいましょう。指摘箇所歯全て直す必要性はなく、明確な意思があってそうしたなら、参考程度に受け取りましょう。
ドキュメント作成にはasciidocを使おう
上記までで、テクニカルライティングの話は終わりです。この章ではドキュメント作成時に用いるツールについての紹介です。私はasciidocというMarkdown記法と似た記法の計量マークアップ言語です。
asciidocを使う理由
私がasciidocをお勧めする理由は以下です。
- バージョン管理が用意
- ブラウザで確認でき、タスクがごちゃつかない
- 視線の流れが上から下なので、見やすい
- Gitのホスティングサービス上で閲覧できる
- 体裁を整えやすい
いろんなサイトでおすすめされているので説明は書かないですが、おすすめです。
以上。
参考文献
- 仲田尚央 「エンジニアが一生困らない ドキュメント作成の基本」 ソシム株式会社 2024年9月27日
- 高橋慈子 「技術者のためのテクニカルライティング入門講座」 株式会社翔泳社 2018年11月19日
- 清水久美子 「意思決定者を動かすテクニックとおもてなしの心 プロの資料作成力」 東洋経済新報社 2012年6月7日
- Qiita : Google社のテクニカルライティングの基礎教育資料がとても良かったので紹介したい