読者のことを考えた文章を書く

この記事を書いたきっかけ

私はソフトウェアについてのユーザ向けヘルプやリファレンスを書いたり校正したり、開発者と仕様や改善点について話し合うことがあります。そのような「事実を伝える文章」を書くとき¹に気をつけている点について言語化してみることにしました。

気をつけている点

内容に誤りがないこと

事実を伝えたいのであれば、誤った記述を避けたいことでしょう。世の中には書いてあることをそのまま鵜呑みにする人がいます。本として出版されているからには内容が正しいに違いない、と思う人もいます。また、著者や発行元に権威があると思われていれば、「間違っているはずがない」と思って読まれることがあります。

しかし誰でも間違えることはあり、そのことは後の自分や他人への教訓となります。しかし、その誤りが致命的・初歩的・頻繁だと、その文章だけでなく、同じ筆者の別の文章や、筆者自身や、筆者の関係先についても心配されたり、信頼性に影響を及ぼすかもしれません²。

正しいかどうかを確認するために校正や校閲といったプロセスがありますが、自分で書いた文章を自分で校正するのは難しいものです。

文章に誤解の余地がないこと

自分では正しく書いたつもりの文章でも、読んでみると正しく解釈できないものになっていることがあります。そうなってしまういくつかの例を取り上げてみたいと思います。

例1) 係り受け

中古のノートパソコンとメモリを買った。

この文からは、ノートパソコンが中古であることが理解できます。しかしこの文の「中古」が係っているのがノートパソコンだけなのか、メモリにも係っているのか断定できません。
メモリが中古であるかそうでないかも確実に伝えたいなら、言い回しを工夫するのがよいでしょう。

例2) 文の区切り

「ここではきものをぬぐべし」のように、どこで区切るかによって複数の解釈ができることがあります。
筆者が意図しない解釈にしか気づかなかった読者は、正しく意味を理解することができないでしょう。また、複数の解釈に気づいた読者は、どれが筆者の意図なのかわからず混乱するでしょう。

例を挙げると、スラドにこのような記事が載ったことがあります。

東京地裁、ソフトバンクに対し名誉毀損を行った投稿者の携帯電話番号開示を命じる
（https://it.srad.jp/story/20/01/24/1554248/ より引用）

コメントとツリーにあるように、このタイトルは

• 東京地裁がソフトバンクに対して"（誰かに対して）名誉毀損を行った投稿者"の携帯電話番号開示を命じた
• 東京地裁が"ソフトバンクに対して名誉毀損を行った投稿者"の携帯電話番号開示を（誰かに）命じた

の二通りに解釈できそうです。

例3) 読者の知識を想定する

私は TTSSH のとある変更履歴をこのように書きました。

PuTTY 形式の秘密鍵フォーマット3 (PPK3) に対応した。

SSH には多くの種類の鍵・アルゴリズム・ファイル形式などが登場します。

• 鍵の用途
  • サーバホスト鍵
  • 通信暗号化のための共通鍵
  • ユーザ認証用の鍵
• 鍵の種類
  • 共通鍵
  • 公開鍵暗号方式の公開鍵
  • 公開鍵暗号方式の秘密鍵
• 鍵のアルゴリズム
  • RSA
  • DSA
  • ECDSA
  • EdDSA
• 秘密鍵が保存されるファイル形式
  • PEM(OpenSSL)形式
  • OpenSSH(bcrypt KDF)形式
  • PuTTY形式
  • SECSH(ssh.com)形式
• 公開鍵が保存されるファイル形式
  • PKCS #8(PKCS8)形式
  • PKCS #1(PEM)形式
  • OpenSSH形式
  • RFC4716形式

このように、指す対象になりそうなものが多くあるため、あまり詳しくない人³にはどの部分のことを指しているのか分かりづらいかもしれないと感じました。
この変更は「PuTTY（PuTTYgen）が生成する "ユーザ認証用の鍵ペアの秘密鍵" の保存ファイル形式にバージョン 3 が登場した⁴。 TTSSH は既存のバージョン 2 ファイル形式に対応していたが、新しいバージョン 3 ファイル形式の読み込みに対応した」という内容です。「フォーマット」とあるのでアルゴリズムのことではないことはわかりそうですが、ファイル形式のことであることがより明確になるよう、次のように修正してコミットしました。

PuTTY の秘密鍵ファイル形式バージョン3 (PPK3) に対応した。

いま振り返ってみると、「PuTTY の秘密鍵ファイルは SSH のユーザ認証に使うものである」ということが省略されているので、それを考慮するとこう書けたかもしれないと思いました。

ユーザの公開鍵認証において、PuTTY の秘密鍵ファイル形式バージョン3 (PPK3) の読み込みに対応した。

書く順番

たいていの読者は文章を上から順番に読んでいきます。ですから重要なことが上に来るように、つまり読者が知りたいであろう順番で書くのが望ましいです。

このように考えると、ソフトウェアの変更履歴の上のほうには「便利になる新機能」や「影響の大きいバグの修正」などが来て、ユーザへの影響が少ない「使用しているライブラリのバージョンを上げた」などは下のほうに配置されるでしょう。

まとめ

「ドキュメントを書かないとうるさく言われるので仕方なく書いている」とか「時間をかけて細かいことを気にして書くのは割に合わない」という人もいます。たしかに、はなからドキュメントを読まない人や、読んでも書いてあることを見逃したり正しく理解しない人もいます。また、書く側が気をつけなくても、頑張って正しく読んでくれる読者もいるかもしれません。

しかし、文章を適当に書いて、いわば校正を読者任せにするのは私の性分ではありません。読者に誤った知識を得させてしまうと、それを訂正するのは難しいものです。また、文章の書き方のせいで読者に悩む時間を費やさせてしまうのは、「事実を伝える」という文章の目的や、「事実を知りたい」という読者の目的を阻むことになるので、看過したいとは思いません。さらに、だれもが気軽に「これは間違っていませんか？」とか「これはAともBとも読めるのですが、どちらが正しい解釈ですか？」という問い合わせをできるわけではありません。ですから、文章を世に出す前にできる限り⁵手を尽くすほうがよいと考えています。

おまけ

私が文章を書くときにこのような細かい点にこだわるようになったのは、いったい何に影響を受けてきたのか、思い当たる点を挙げてみます。

• 翻訳者の知人から聞いた「英文の契約書のコンマ1つの有無で意味が変わり、数百万ドルの損失が出たことがある」というエピソード
  おそらく Rogers Communications に関する裁判のこと

• Microsoft の CreateFileA のドキュメントの Minimum support に "Windows XP" と書かれていること
  実際は Windows95, Win32s, NT 3.x からあるようです。さすがに CreateFileA ならこの記述はおかしいと気づけそうですが、それほど有名ではない関数だと気づかないかもしれません。

• 「火事で窓ガラスが溶ける」という原稿を書いたら、出版社の校閲さんから「溶けずに割れます」と返ってきたエピソード

やっぱり新潮社の校閲は凄いな……。
火事で窓ガラスが溶けると書いたら、溶けずに割れますと資料付きで修正が入っていた。
勉強になりましたm(__)m pic.twitter.com/05PKPMtOsR

— 知念実希人　小説家・医師 (@MIKITO_777) August 4, 2018

• RFC が「MUST」「MUST NOT」「SHOULD」「SHOULD NOT」「MAY」を使い分けていること

• 運輸安全委員会の鉄道事故調査報告書が「認められる」「推定される」「考えられる」「可能性が考えられる」を使い分けていること⁶

• 特許の出願書類を書く仕事をしている知人に「誰がどう読んでも、書いた意図とは異なる読まれ方をしない文章」を書くのが仕事だ、と聞いたこと

• 「送信するものに関しては厳密に、受信するものに関しては寛容に」という原則

• 新人だったころ、分からないことをすぐ先輩に聞きにいくと「man を読め man を」と言われたこと
  このように言われるということは、マニュアルが整備されているはずです。

• 過去に何度も繰り返されたのと同じような初歩的な質問が流れたときに「RTFM」とか「過去ログ読め」という回答が返ってくる技術系メーリングリスト⁷にいたこと
  このように言われるということは、マニュアルや過去ログが参照できるようになっているということです。

1. 私は「面白く読ませる文章」や「炎上させるための文章」を書くことはないので、そういう文章には当てはまらないこともあるでしょう。 ↩

2. 文章ではなくソフトウェアですが、Sendmail から qmail へ、BIND から NSD や Unbound への移行を勧める人がいたり、OpenSSL から LibreSSL が fork しました。 ↩

3. 私もあまり詳しくないので、このリストもなにか間違っているかもしれません。 ↩

4. PuTTY の変更履歴では、"Upgraded private key file format to PPK3, with improved passphrase hashing and no use of SHA-1." となっています。 ↩

5. この「できる限り」に個人差がある、ということだと思いますが ↩

6. いつも3ページあたりに、用語の取扱いについて書かれています。報告書の一例 ↩

7. 「技術系メーリングリストで質問するときのパターン・ランゲージ」,「真・技術系メーリングリスト FAQ」,「How to Report a Bug ( PHP)」などには、過不足のない（聞き返す必要のない）質問やバグ報告の書き方が説明されています。 ↩