技術をわかりやすく伝えるテクニカルライティングのtips

本エントリはZOZO Advent Calendar 2023 シリーズ4の5日目の記事です。

私はDevRelとして、エンジニア向けの社内報でテクニカルライティングtipsを紹介する連載をしています。これまで自分が技術同人誌を書いて校正された経験を元に、少しずつノウハウを共有してみようとはじめました。数ヶ月続けた連載の内容に加筆・修正を加え、まとめたものを本記事で公開します。

一文を短くする

一文は50文字程度までとしましょう。それだけで文章は見違えるほど良くなります。

よくない例

改善したかったのは文のはじまりから結論に至るまでが長く読み手に負担をかけるところで、その改善方法として文を短くすることを紹介しており、これは文の誤りや誤解を招く表現を防ぐ効果もあります。（93文字）

改善例1. 分割する

改善したかったのは一文が長いことです。結論に至るまでが長い文は読み手に負担をかけます。文を短くするとこの負担を軽減できます。また文の誤りや誤解を招く表現を防ぐ効果もあります。（18文字＋23文字＋18文字＋25文字）

改善例2. 箇条書きを使う

改善したかったのは一文が長いことです。理由は次のとおりです。

• 長い文は読み手に負担をかけるため
• 文の誤りや誤解を招く表現を防ぐため

改善例では言いたいことが明確です。「何の話だっけ？」と前に戻って読み直すことも減ります。一つの文に入れる事柄は一つだけとする「一文一義」を守り、短い文にすると理解しやすくなります。

正式名称・正しい名前で書く

”JavaScript”を”Java”と略すと別の技術になってしまうように、正しく書かないと別のことを意味したり、誤りとなったりすることがあります。大文字・小文字の違いや、スペースの有無も気をつけましょう。名前が誤っていると、「名前以外にも誤りがあるかもしれない」と文章全体の信頼性が下がってしまいます。

textlintを使うと間違えそうな用語を自動的にチェックできます。次のようなリストを作って誤りがあったものを追加していくと便利です。

同じ助詞を連続して使わない

文中で同じ助詞が連続すると読みにくくなります。例えば「今日はAさんは定例会議は欠席します」といった文です。次のコツを意識すると改善できます。

改善方法1. 語順を適切に変える

今日はAさんは定例会議は欠席します。
　　　　　　　↓
Aさんは今日の定例会議を欠席します。

主語を先頭に出すことで自然と助詞が変わります。

改善方法2. 意味が明確な表現に置き換える

データベースの接続でエラーでトラブルシューティングを行いました。
　　　　　　　↓
データベースの接続時にエラーが発生したため、トラブルシューティングを行いました。

助詞には複数の意味があります。「で」であれば「場所・時間」「手段・方法・材料」「原因・理由」などです。同じ助詞が続くと、読み手はどの意味で捉えるべきかわからず混乱します。明確な表現に置き換えてみましょう。

改善方法3. 複雑な文を助詞で繋げている可能性があるので、分割を検討する

この問題を解決するアプローチとして、変数を参照できる範囲を小さくするために、処理を関数にまとめるという手法がよく利用されます。
　　　　　　　↓
この問題を解決するアプローチとして、処理を関数にまとめる手法がよく利用されます。これにより変数の参照範囲を小さくできます。

「を」が繰り返し使われ読みづらくなっている例です。完全に連続していなくても、一文に同じ助詞が多いと理解しづらくなります。長すぎる修飾を避け分割すると読み手の負担を軽減できます。

参考情報：textlint-rule-no-doubled-joshi https://github.com/textlint-ja/textlint-rule-no-doubled-joshi

主語と述語を対応させる

文から修飾語を除いて主語と述語だけにしたとき、意味が成り立たない状態のことを「ねじれ」といいます。主述のねじれが起きていると、読み手は内容の理解に時間がかかりストレスを感じます。文法上の誤りに該当するため修正しましょう。

よくない例

新しいシステムの特徴は、高度な並行処理と最適化が可能であり、業務を効率化できます。

修飾を省くと「特徴は効率化できます」という文になり、違和感にすぐ気付くのではないでしょうか。

改善例

1. 新しいシステムの特徴は、高度な並行処理と最適化が可能であり業務を効率化できることです。
2. 新しいシステムは高度な並行処理と最適化が可能であり、業務を効率化できます。
3. 新しいシステムの特徴は、高度な並行処理と最適化です。これにより業務を効率化できます。

いずれも文法上の誤りはなくなっています。1は修飾が長いため主語と述語がやや離れており、2や3の方が読者への負担が軽くなるでしょう。ただしそれぞれの文で意味合いが少し異なっているので、書き手の伝えたい内容と合致させる必要があります。

ねじれを防ぐコツ

ねじれは短文であれば発生しにくいのですが、思うままに長く書いているとうっかりミスが入り込みやすくなります。ねじれを防ぐコツは次のとおりです。

• 一文を短くする
• 主語と述語を近づける
• 声に出して読んでみる

この3つを意識すると、ねじれだけでなくさまざまな誤りに気付くことができます。文はコードと同じで、書き手よりも読み手の方が多いものです。たくさんの読み手が何度も読み直し理解に時間がかかると、多くの時間をロスしてしまいます。スムーズなコミュニケーションのために、ぜひ試してみてください！

なるべく肯定文で書く

否定的な表現を使うと文が曖昧になり、疑問や誤解を招きやすくなります。肯定文で表現できる場合は肯定文を使いましょう。

よくない例

マージしたブランチは、残したままにしないでください。

改善例

マージしたブランチは、削除してください。

「残したままにしないでください」だけの場合、それならばどうすればいいのかと読者に疑問を抱かせてしまいます。特に読み手の行動を促そうとするときは、やってほしいことを肯定文で書き明確にします。このtipsの見出しも「否定文を使わないでください」という表現は避けています。

例外

例外として、注意・禁止事項は「してはいけないこと」を明確に伝えるために否定表現を使います。

例：ゲームデータをセーブしています。本体の電源を切らないでください。

冗長な表現を排除する

一文を短くするために、可能な限り冗長な表現を排除しましょう。改善方法と例を紹介します。

改善方法	よくない例	改善例
「すること」を省く	確認することができます	確認できます
「というもの」を省く	冗長な表現というものがあります	冗長な表現があります
「〇〇をする」「〇〇を行う」は「〇〇する」に縮める	開発を行う	開発する
「〜かどうか」を「〜か」に縮める	圧縮できるかどうか検証します	圧縮できるか検証します
「どのように〜か」を「〜方法」に縮める	どのように実現するか紹介します	実現方法を紹介します
「どれぐらい〜か」を「〜量・〜数」に縮める	どれぐらい削減できるか調査しました	削減量を調査しました
「〜なります」は「です」で断定する	こちらが改善した結果になります	こちらが改善した結果です

指示代名詞の多用を避ける

指示代名詞とは「これ」「そこ」「あちら」など、事物・場所・方角などを指し示すときに用いる代名詞です。文中に指示代名詞が増えると、何を指しているのかわかりづらくなります。

例：アプリケーションでの効率的な位置情報の取得は開発者にとって大きな課題であり、Location APIの活用が非常に重要です。これ には、さまざまなメリットとデメリットが存在します。

「これ」が示すものは何でしょうか。「Location API」「Location APIの活用」もしくは「位置情報の取得」かもしれません。読者は後続の文を読み何を指すのか察する必要があります。指示代名詞を使わず「Location APIには」と明示すると読者に負担をかけずに済みます。指示語を使う場合でも「これには」よりも「このAPIには」と指示連体詞を使った方がわかりやすくなります。

---

本記事の内容は技術書典15で頒布した技術同人誌「Code Polaris Tech Book vol.2」と一部重複するところがありますが、同一ではありません。同人誌版では紙の書籍独特の注意事項を書いたり、社内報では社内で使いそうな文例を考えたり、読み手に合わせて内容を変えています。読み手の立場になって考えることも、テクニカルライティングの重要なテクニックのひとつです。そういった全体構成に関わる知識はまだ勉強中の点が多いため、もっと学んでいきたいと思います。