こんにちは。エンジニアは業務としてドキュメントを書く機会が多々ありますが、最近私が関わっているプロジェクトでは、結構な量のドキュメントを作成しています。そんな折、目に留まったのがテクニカルライティングという言葉でした。
業務や自習で普段から技術文書には接していますので、それらを何となく真似て書いていましたが、体系立った技術があるのなら触れてみよう、と思います。
技術的な情報を利用者に分かりやすく伝えるための文章技術です。技術文書は文章量が多く、また専門知識を多く含むため、分かりづらくなりがちです。
エンジニアでも難しく感じるものですから、専門外の人にとってはことさらそう映るものと思います。
一つの文章では一つの主題に絞って書くという意味です。この場合の文章とは、句点「。」を区切りとした文のことを指します。複数の内容が一文に盛り込まれていると、何を伝えようとしているのかが読み手に分かりにくくなります。
〜だが、〜のでを多用して文章を複数つなぐのは、ありがちなアンチパターンです。言いたいことを垂れ流すように書いていると、こうなりやすいと思います。文章の長さだけではなく、伝えたいことが最後に来てしまうのも良くありません。
適切な文字数については、媒体によって結構ばらつきがあるようです。中高生向けでは25〜40文字、日経電子版や朝日新聞デジタルは21〜40文字、NHKは60〜80文字という調査結果を出している方がいました。
また、私が先日読んだテクニカルライティングの書籍では「50文字以内で」と書かれていました。この文字数には根拠が示されていませんでしたが、感覚的には妥当な文字数に思えます。あくまで感覚的には、ですが…。
会話でも「言いたいことを先に言え」という指摘を受けたことがあると思います。最後まで読まないと分からない文章は、読み手に余計な負担をかけてしまうため、技術文書としては良くありません。
「何をすればいいのか」がはっきりしている文章を意識しましょう。また、「〜が必要です」という婉曲的な表現もよく使われますが、これも「〜してください」と書き換えたほうが、より伝わりやすくなります。
例えば開発環境を作るための作業手順書では、こういった直接的な書き方が必要になると思います。
「○○でない時は××しない」といった否定表現を、コード内のコメントやgitのコミットコメントでたまに見かけますね。このような二重否定は直感的に分かりづらいため、肯定形に書き換えることを検討しましょう。
文章が曖昧になりやすい表現の代表です。書き手が「他にも色々あるから」と考えていると使いがちな表現ですが、「じゃあ他には何があるの」というツッコミを招きます。「など」を使う場合、「など」が何を指すのかを明確にしましょう。
文章中には強調のためのカギ括弧「」と、語句の言い換えのための丸括弧()が基本で、それら以外の括弧を多く使うと、括弧の意味がぶれてしまいます。
なお、補足や私見を書くために丸括弧を使うのは非推奨です。個人ブログの私的な文章であれば、気持ちを表す書き方として丸括弧を使う表現もありだと思いますが、技術文書では冗長になるだけです。
htmlにおけるh2、h3といったタグが、まさに階層構造を示すためのものです。マークダウン形式では自然と階層構造を意識した書き方になるので、技術文書を作成するのに向いた記法だと感じます。
技術文書ではほとんど必須と言ってもいい箇条書きですが、その項目数については、マジックナンバーと言われる数があります。私が読んだ本では7、ネット上の記事では3だったり5だったりと、これも文字数のように一定しません。
とはいえ、5〜7程度の数が感覚的には妥当だと思います。これ以上の項目数になってしまう場合、分類を考え直したり不要な項を削除することを検討したほうが良さそうです。
こうしてまとめてみると、自発的に気をつけていたこともあれば、盲点だったところもありました。結局は冒頭に挙げた「読み手を意識する」に帰結するのかなと思います。
正確であることは大前提として、「誰に何を伝えたいのか」、「どうしてほしいのか」を考慮して、読み手の負担を減らすことを心がけていこうと思います。