Tech

ドキュメント作成の技術「テクニカルライティング」とは

投稿日:

はじめに

こんにちは。エンジニアは業務としてドキュメントを書く機会が多々ありますが、最近私が関わっているプロジェクトでは、結構な量のドキュメントを作成しています。そんな折、目に留まったのがテクニカルライティングという言葉でした。
業務や自習で普段から技術文書には接していますので、それらを何となく真似て書いていましたが、体系立った技術があるのなら触れてみよう、と思います。

テクニカルライティングとは

技術的な情報を利用者に分かりやすく伝えるための文章技術です。技術文書は文章量が多く、また専門知識を多く含むため、分かりづらくなりがちです。
エンジニアでも難しく感じるものですから、専門外の人にとってはことさらそう映るものと思います。

少しでも分かりやすく、簡潔にする

一文一義

一つの文章では一つの主題に絞って書くという意味です。この場合の文章とは、句点「。」を区切りとした文のことを指します。複数の内容が一文に盛り込まれていると、何を伝えようとしているのかが読み手に分かりにくくなります。

長くしすぎない、繋げすぎない

〜だが〜のでを多用して文章を複数つなぐのは、ありがちなアンチパターンです。言いたいことを垂れ流すように書いていると、こうなりやすいと思います。文章の長さだけではなく、伝えたいことが最後に来てしまうのも良くありません。

長さの目安は?

適切な文字数については、媒体によって結構ばらつきがあるようです。中高生向けでは25〜40文字、日経電子版や朝日新聞デジタルは21〜40文字、NHKは60〜80文字という調査結果を出している方がいました。
また、私が先日読んだテクニカルライティングの書籍では「50文字以内で」と書かれていました。この文字数には根拠が示されていませんでしたが、感覚的には妥当な文字数に思えます。あくまで感覚的には、ですが…。

伝わりやすく書く

まず主題を書く

会話でも「言いたいことを先に言え」という指摘を受けたことがあると思います。最後まで読まないと分からない文章は、読み手に余計な負担をかけてしまうため、技術文書としては良くありません。

動詞で書く

「何をすればいいのか」がはっきりしている文章を意識しましょう。また、「〜が必要です」という婉曲的な表現もよく使われますが、これも「〜してください」と書き換えたほうが、より伝わりやすくなります。
例えば開発環境を作るための作業手順書では、こういった直接的な書き方が必要になると思います。

否定表現の使い方に気をつける

「○○でない時は××しない」といった否定表現を、コード内のコメントやgitのコミットコメントでたまに見かけますね。このような二重否定は直感的に分かりづらいため、肯定形に書き換えることを検討しましょう。

「など」を使いすぎない

文章が曖昧になりやすい表現の代表です。書き手が「他にも色々あるから」と考えていると使いがちな表現ですが、「じゃあ他には何があるの」というツッコミを招きます。「など」を使う場合、「など」が何を指すのかを明確にしましょう。

読みやすさの向上

括弧は2種類

文章中には強調のためのカギ括弧「」と、語句の言い換えのための丸括弧()が基本で、それら以外の括弧を多く使うと、括弧の意味がぶれてしまいます。
なお、補足や私見を書くために丸括弧を使うのは非推奨です。個人ブログの私的な文章であれば、気持ちを表す書き方として丸括弧を使う表現もありだと思いますが、技術文書では冗長になるだけです。

階層構造で示す

htmlにおける h2h3 といったタグが、まさに階層構造を示すためのものです。マークダウン形式では自然と階層構造を意識した書き方になるので、技術文書を作成するのに向いた記法だと感じます。

箇条書きの使い方について

技術文書ではほとんど必須と言ってもいい箇条書きですが、その項目数については、マジックナンバーと言われる数があります。私が読んだ本では7ネット上の記事では3だったり5だったりと、これも文字数のように一定しません。
とはいえ、5〜7程度の数が感覚的には妥当だと思います。これ以上の項目数になってしまう場合、分類を考え直したり不要な項を削除することを検討したほうが良さそうです。

さいごに

こうしてまとめてみると、自発的に気をつけていたこともあれば、盲点だったところもありました。結局は冒頭に挙げた「読み手を意識する」に帰結するのかなと思います。
正確であることは大前提として、「誰に何を伝えたいのか」、「どうしてほしいのか」を考慮して、読み手の負担を減らすことを心がけていこうと思います。

おすすめ書籍

技術者のためのテクニカルライティング入門講座 これなら通じる技術英語ライティングの基本

blog-page_footer_336




blog-page_footer_336




-Tech
-

執筆者:

免責事項

このブログは、記事上部に記載のある投稿日時点の一般的な情報を提供するものであり、投資等の勧誘・法的・税務上の助言を提供するものではありません。仮想通貨の投資・損益計算は複雑であり、個々の取引状況や法律の変更によって異なる可能性があります。ブログに記載された情報は参考程度のものであり、特定の状況に基づいた行動の決定には専門家の助言を求めることをお勧めします。当ブログの情報に基づいた行動に関連して生じた損失やリスクについて、筆者は責任を負いかねます。最新の法律や税務情報を確認し、必要に応じて専門家に相談することをお勧めします。


comment

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

CAPTCHA


関連記事

祝!iOS15でハーフモーダルが追加

1 はじめに2 早速使ってみる2.1 準備2.2 実装2.3 detents2.4 コードでの高さ切り替え2.5 モーダル内のスクロール許可2.6 グラバーの表示2.7 角丸2.8 親Viewとの併用 ...

Go言語

GoフレームワークGinでミドルウェアを使ってログインAPIを実装

1 はじめに2 ログインAPIの作成3 ログインのセッション管理4 ミドルウェア4.1 gin.Default()4.2 Logger4.3 Recovery4.4 sessions5 独自ミドルウェ ...

ReactNative環境構築[Android/iOS]

1 はじめに2 準備2.1 HomeBrewをインストール2.2 node.jsのインストール2.3 Watchmanのインストール2.4 React Native CLIのインストール2.5 サンプ ...

Xcode11のデバッグ機能

1 はじめに2 Device Conditions2.1 Thermal state condition2.2 Network link condition3 Environment Override ...

C# マルチキャストデリゲートの備忘録

1 はじめに2 C#のデリゲートについて2.1 デリゲートの定義3 マルチキャストデリゲートについて3.1 追加方法3.2 削除方法4 さいごに5 おすすめ書籍 はじめに こんにちはsuzukiです。 ...

フォロー

blog-page_side_responsive

2019年2月
 12
3456789
10111213141516
17181920212223
2425262728  

アプリ情報

私たちは無料アプリもリリースしています、ぜひご覧ください。 下記のアイコンから無料でダウンロードできます。