🗒️

技術文書を書くときの個人的なルールをまとめてみた

2022/07/29に公開

技術文書

idea

技術文書に限らず、Slack のチャットやメールなど、コンピューターを使って文章を書く際に個人的なルールがあります。

これらのルールの多くは、サポートエンジニアをやっていた時に仕込まれたものや、オープンソースの翻訳プロジェクトに携わっていた時にのルールが元となっています。

ふだん無意識にやっていることを文章化してみようと思います。

1 文の長さを短くする

日本語は、句点 (、) を利用することで 1 文の中に複数の内容を含めることができてしまいます。しかし読む側としては 1 文が長くなると、内容が頭に入りにくくなってしまいます。

そのため、1 文の長さを短くするように、長くても約 70 ～ 80 文字に抑えるようにしています。目安として、メーラーの自動折り返し機能が働かない程度の文字数に収まるように書いています。

全角文字と半角文字

英数字、および記号については、基本的に半角文字で書いています。

カタカナ、および句読点については全角文字で書いています。よく技術文書では、句読点 、 。 を半角 , . で書いてあるものがありますが、あれはなんの流派なんでしょうね。

また、読みやすさのために、全角文字と半角文字の間は半角スペースを 1 つ入れて書いています。ただし、これには一部例外があります。

半角スペースを入れない条件

全角句読点 、 。 の後ろに半角文字が続く場合
半角カッコの始まり ( の後ろに全角文字が続く場合
全角文字の後ろに半角カッコの終わり ) が続く場合
半角文字の後ろに全角カッコの始まり 「 が続く場合
全角カッコの終わり 」 の後ろに半角文字が続く場合

このルールは、 Play Framework 翻訳プロジェクトのルールが、体に染み付いてしまったものです。

英語をカタカナ表記する際の長音符号 (ー) を省略しない

「コンピューター」や「プリンター」、「エクスプローラー」など、末尾の長音記号を省略しないように記載しています。

このルールは、2008 年にマイクロソフトが表記ルールを変更したときから適用しています。長い物には巻かれろ。

「上下左右」を使わない

「上に記載したとおり」や「下のとおりまとめます」のような、位置を表す上下左右を使わないようにしています。

これは、文書を版組した際に左右にずれ込んだりする可能性があるためです。

次のとおりに言い換えることが多いです。

「 上に記載 したとおり」→「前述したとおり」
「 下記の とおりにまとめます」→「次のとおりにまとめます」

固有名詞は無理にカタカナにしない / 正しい綴りを調べる

例えば「Java」は、「java」や「JAVA」、「ジャバ」ではありません。「 Java 」です。公式サイトの綴りを確認するクセを付けましょう。

「IntelliJ IDEA」などはクセがあって面白いですね。

また、2 語の英語がつながっているように見えて、実は 1 語であるものもよくあります。例えば「Notebook」などです。こういうものを調べてみると、新たな発見があるかもしれません。

漢字を多用しすぎない

「御覧の通り」を「ご覧のとおり」と書くなど、あまり漢字が多くならないように気をつけて書いています。極端にひらがなだらけや漢字だらけになると読みにくかったり、堅苦しい文章になったりします。

ひらがなを使っている言葉 (一部)

通り → とおり
お願い致します → お願いいたします
様々 → さまざま
行う → おこなう (これは送り仮名がよく分かっていないだけ)

敬語表現を正しく使う

よく間違えやすいのは「御社」と「貴社」の使い分けです。

「御社」は 話し言葉 ですので、文章では使いません。正しくは 書き言葉 の「貴社」です。「貴社」は、会話では使わないように気をつけましょう。

その他にも、「ご覧いただければ」のように、敬語表現が二重にならないように気をつけています。この例の場合は「見ていただければ」もしくは「ご覧ください」と言い換えています。

また、敬語の「いただく」を「頂く」と書くのは誤りです。「頂く」は「貰う」の謙譲語ですので、補助動詞の「いただく」とは意味が違います。

「思います」を使わない

「思います」・・・それってあなたの感想ですよね？

というのは半分くらい冗談ですが、サポートエンジニア時代に指摘されたので、「考えられます」や「存じます」に書き換えています。

ダメな例

このエラーの原因ですが、設定に誤りがあるのではないかと思います。
再度エラーが発生した場合、ログファイルを送っていただければと思います。

書き換え

このエラーの原因ですが、設定に誤りがあると考えられます。
エラーが発生した場合、ログファイルを送っていただければと存じます。

送り仮名を省略しない (2022-08-05 追加)

「打合せ」ではなく「打ち合わせ」、「申込み」ではなく「申し込み」のように、送り仮名は省略しないようにしています。

例

打合せ → 打ち合わせ
申込み → 申し込み
切替え → 切り替え

送り仮名をチェックするために、Microsoft Word にて次のとおり設定しています。

「ファイル」→「オプション」を開く。
「Word のオプション」画面にて、「文字校正」→「文書のスタイル」の「設定」ボタンをクリックする。
「送り仮名の基準」を「公用文」に設定する。(※本則でも可)

-- 以上、その他に気がついたら追記します --