テクニカルライティング小ネタ

今日もテクニカルライティングです。それではいってみましょう。

単語

世界で最も優れた文章は主に単語で構成されている。

新しい用語や聞き慣れない用語を定義する

　対象読者の一部または全員にとって馴染みのない用語は、次の2つの戦術のいずれかを実施

• その用語がすでに存在する場合は、既存の説明にリンクする(車輪を再発明しない）。
• あなたの文書がその用語を紹介している場合は、その用語を定義する。あなたの文書が多くの用語を紹介している場合は、用語集に定義を集約する。

用語を一貫して使用する

　メソッドの途中で変数名を変更すると、コードはコンパイルされません。それと同様に、文書の途中で用語の名前を変更すると、あなたのアイデアは（ユーザーの頭の中で）コンパイルされません。

略語を正しく使う

　文書やセクションの中で見慣れない略語を最初に使用する場合は、完全な用語をスペルアウトし、その略語を括弧で囲む。スペルアウトしたものと頭字語の両方を太字にする。下記の表から、USA（United States of America）

同じ文書の中で、頭字語と頭字語でないものを行ったり来たりしない

頭文字を使うか、完全な用語を使うか？

　確かに、頭字語は適切に導入し、使用することができますが、頭字語は使うべきでしょうか？ 確かに頭字語は文章のサイズを小さくします。例えば、ASAPはAs Soon as possibleより短いです。しかし、頭字語は実際には抽象化のレイヤーに過ぎず、読者は最近覚えた頭字語を完全な用語に精神的に拡大しなければなりません。例えば、読者は頭の中でASAPをAs Soon as possibleと変換するので、”短い”頭字語は実際には完全な用語よりも処理に少し時間がかかります。

多用される略語は、独自のアイデンティティを確立します。何度も使用されると、一般的に読者は頭字語を完全な用語に拡大することをやめてしまいます。例えば、多くのウェブ開発者は、USAが何に拡張されるかを忘れてしまっています。

略語のガイドラインは以下の通りです：

• 数回しか使わないような略語は定義しないこと。
• 以下の両方の条件を満たす場合に略語を定義すること：
  • 頭字語は完全な用語よりもかなり短い。
  • 頭字語は文書中に何度も登場する。

あいまいな代名詞を認識する

多くの代名詞は、前に紹介した名詞を指します。このような代名詞は、プログラミングにおけるポインタに似ています。プログラミングにおけるポインタと同様に、代名詞はエラーを引き起こしがちです。代名詞の不適切な使用は、読者の頭の中でnull・ポインタのエラーと同等の認知を引き起こします。多くの場合、代名詞を避けて名詞を再利用すればよい。

それと彼ら

以下の代名詞は技術文書で最も混乱を招く。

• それ
• 彼ら、彼女ら
  　英語の三人称代名詞 “they” には、「彼ら」「彼女ら」「それら」という複数の意味があり、日本語訳や技術文書での使用時に混乱が生じやすいです。一方、”it” は「それ」と訳されることが多いですが、用法が多岐にわたるため、これもまた誤解や混乱の原因となる。

主な混乱の原因

• “they” の多義性
  • “they” は「彼ら（男性複数）」「彼女ら（女性複数）」「それら（無生物や動物の複数）」と訳されます。
  • 技術文書では、対象が人か物かによって訳語が変わるため、文脈を誤解しやすいです。
• “it” の多様な用法
  • “it” は「それ」以外にも、天候、時間、距離、形式主語・目的語など多様な用途があります。
  • 技術文書で「it = それ」と安易に訳すと、実際には「その状況」「その事象」「その操作」など、より抽象的な意味を持つ場合があり、誤解を招くことがあります

技術文書での注意点

1. “they” の訳語選択

• 機械や装置の部品など無生物が主語の場合は「それら」。
• 人（ユーザー、管理者など）が主語の場合は「彼ら」または「彼女ら」。
• 文脈によっては「それらのもの」「当該項目」など、より具体的に訳すと誤解を防げます5。

2. “it” の訳語選択

• 単純な物体や明確な対象の場合は「それ」。
• 状況や事象、抽象的な内容を指す場合は「それ」以外の訳（「その現象」「その処理」「その場合」など）を検討する

これとそれの使い方を明確にするために、以下のいずれかの方法を使う。

１．例　変更前

　プロセスを実行すると、パーミッションが設定され、ユーザーIDが生成される。これにより、ユーザーはアプリを認証できる。

２．例　変更後

　このユーザーIDによってユーザーは認証される。
権限を設定するプロセスで、ユーザーを認証します。
パーミッションとユーザIDの組み合わせにより、ユーザが認証されます。

３．これとそれの使い方を明確にするために

• これまたはそれを適切な名詞に置き換える。
• このまたはそのの直後に名詞を置く。
  

短い文章

　ソフトウェア・エンジニアは一般的に、次のような理由から実装のコード行数を最小限に抑えようとする。

• 短いコードは、一般的に他の人にとって読みやすい。
• 長いコードよりも短いコードの方が保守しやすい。
• 余分なコード行は、新たな障害点をもたらす。

実際、テクニカルライティングにも同じルールが適用される。

• 短い文書は長い文書よりも速く読まれる。
• 長い文書よりも短い文書の方が、一般的にメンテナンスが簡単。
• 長い文書よりも短い文書の方が保守しやすい。

　最短のドキュメントの書き方を見つけるには時間がかかりますが、結果的には価値があります。短い文章は長い文章よりも力強く伝わり、短い文章は長い文章よりも理解しやすい。

一文を一つのアイデアに集中させる

悪い例（複数のアイデアが混在）

　その代表例である液晶ディスプレイは，テレビでもスマホでも使われており，それは薄くてきれいな画像だから，私たちの目を楽しませると同時に多くの情報を与えてくれるのだが，最近では新しいディスプレイとして有機ELが開発され，スマホなどで実用化されたと聞いている。

この文は、液晶ディスプレイの用途・特徴・新技術の登場など、複数のアイデアが一文に詰め込まれている。

良い例（一文を一つのアイデアに集中させる）

液晶ディスプレイはテレビやスマートフォンで使われています。
液晶ディスプレイは薄型で、きれいな画像を表示できます。
このため、私たちの目を楽しませ、多くの情報を提供します。
最近では、有機ELディスプレイが新たに開発されました。
有機ELはスマートフォンなどで実用化されています。

長い文章をリストに変換する

長い文章（変換前）

本製品を安全にご使用いただくためには、まず電源ケーブルが正しく接続されていることを確認し、その後電源スイッチを入れてください。また、使用中は製品を高温多湿の場所に置かないようにし、異常な音やにおいがした場合は直ちに使用を中止し、サポートセンターに連絡してください。

リスト形式（変換後）

本製品を安全にご使用いただくには、次の点にご注意ください。

• 電源ケーブルが正しく接続されていることを確認し電源スイッチを入れてください。
• 使用中は、製品を高温多湿の場所に置かないでください。
• 異常な音やにおいがした場合は、直ちに使用を中止しサポートセンターに連絡してください。

最後に

　どうでしたか？１つ１つはとても単純ですが、しっかり習得したいですね。

成果を生み出すテクニカルライティング トップエンジニア・研究者が実践する思考整理法 [ 藤田肇 ] 価格：2,508円（税込、送料無料) (2025/6/3時点) 楽天で購入