Zenn
📝

ソフトウェアエンジニアのための文章の書き方

2024/12/21に公開
テクニカルライティング
文章
技術文書
公用文
tech

はじまり

上司からの言葉

筆者が大学を卒業して会社員になり、しばらく経ったときのことです。アプリケーションの不具合を修正するために書いたリリース文書の承認を得ようとしたときに、上司に言われた言葉が忘れられません。

😊「君の文章は崩壊しているよ。まず接続詞がおかしいし、そんな表現は日本語にはないです。それに『動作が重い』って何？『致命的な不具合』って何？具体性に欠けています。ちゃんとした文章を書いてください」

🤬「(は？見りゃわかんだろ)」

と怒りを覚えつつも、これまで指摘されたことのない文章力について考える機会が与えられたのでした。

🤔「(確かに…『重い』とはなんだろうか？なにをもって『致命的』なのだろうか？)」

😊「公用文の書き方を読んでおいてね」

🙄「わかりました…」

いつかこの上司を見返してやろうと思いつつも、筆者の転職によりその機会が来ることはありませんでしたが、この文書を書いていることからもわかるように、彼の言葉は私の人生に大きく影響を与えてくれました。

日本語は易しい

日本語はとても易しい言語です。なぜなら語順がめちゃくちゃでも、主語が抜けていても、接続詞が間違っていたとしても、文脈からなにを伝えようとしているのかが推測できるので、それなりに伝わります。

× 「されちゃったの!?『寄生』!!」
○ 「あなたはキノコに寄生されてしまったのですか!?」

これは極端な例で、こんなよそよそしく怪しい日本語を書くことはありませんが、これだけでも日本語の適当さがわかります。

また、あとで言及する次の3つの文章も、細かなニュアンスな違いはあれど、同じようなことを表しています。

「今日、彼は早く学校に来た」
「彼は今日、早く学校に来た」
「彼は学校に、今日早く来た」

さらに口語であれば「早く来たんだよ、彼！学校に今日！」のような破滅的な日本語も通じてしまうところが易しくも恐ろしいところです。はてさて、どうしたものでしょうか。

日本語は難しい

しかし、めちゃくちゃな表現ができるということは、その内容によっては曖昧さが生じることになります。近所のとある公園に、

🪧バットを使った野球やサッカーで、近所の方や公園利用者に迷惑になる行為は禁止します

と書かれた看板がありました。これを見た瞬間フフッとなった人はおそらくそれなりに気をつけて日本語を書く癖がある方だと思いますがどうでしょうか。

これの表現したいことは「ボールが遠くに飛ぶような球技を行うことは事故に繋がるため禁止」であると筆者は捉えているのですが、文章力不足でおかしな表現になっています。

なぜこれがおかしな文書なのでしょうか？それはこの文章が曖昧なゆえに、次の疑問が生まれるからです。

  • バットを使わない野球があるのか？
  • バットを使ったサッカーがあるのか？
  • 野球とサッカーのほかにバットを使ったスポーツがあるのか？
  • 野球やサッカーをすることによってなにが迷惑になるのか？

ツッコミどころが満載ですが、なぜこのような文章を書いてしまうのでしょうか？

大きな理由のひとつは、誰も日本語の書き方を教えてくれないからです。もしかしたら義務教育の指導要領に含まれているのかもしれませんが、少なくとも筆者はそのような指導を受けた記憶がありません。

多くの人は大人になり、社会人になれば、恥をかかないように最低限の敬語は使えるようになりますが、よく見る有名企業が出す書面の内容と比較すると自分が書いた文章が稚拙に見えます。

いつまでも程度の低い文章を書いているわけにもいかないので、あちこちから使えそうな表現を真似して大人の文章ごっこをし始めるわけですが、そこでふと気づくのです。「そういえば、正しい日本語というものはどう書くのだろうか？」と。

なにか決められた規則は存在しない

筆者が見渡す限り正しい日本語の書き方というものは存在しません。ですが、それに準ずるものとして公用文があります。公用文とは官公庁で主に使用される日本語の書き方で、これについても公式の規則はありませんが、各参考文献では共通して同じようなことが書かれています。

この文書の目的

この文書はソフトウェアエンジニアの文章力向上を目的として、公用文の書き方を参考に、最低限抑えておくと役に立つ日本語の書き方についてまとめています。よく言われるものから筆者の経験上重要だと感じたを内容を中心に、例を交えて説明しています。

公用文というと堅苦しい印象を受けるかもしれませんが、技術文書(テクニカルライティング)のほか、あらゆる状況に応用できる要素が多いので、覚えておいて損はありません。

参考文献

日本語の基本

基本形に沿う

  • 基本的には日本語の自然な語順であるSOV(主語→目的語→動詞)に準じるようにします。
    • ○「私はペンを持っています」
    • ○「C言語はベル研究所で開発されました」
  • 語順を意識して、表現が意図したものになるか確かめます。
    • ○「今日、彼は早く学校に来た」(ほかの日はわからないが、今日は学校に早く来た)
    • △「彼は今日、早く学校に来た」(今日はいつもより早く学校に来た)
    • △「彼は学校に、今日早く来た」(いつも学校に来ているかはわからないが、今日早い時間に学校に来た)
  • 暗黙の文脈が生まれる場合には、言葉が足りないので補う必要があります。
    • ○「今日、彼はいつもより早く学校に来た」
    • ○「今日、彼は朝一番に母校を訪れた」
  • 頭が赤い魚を食べる猫は極端な例ですが、日本語の自由度の高さによって、たったこれだけの文章でたくさんの解釈を生み出せます。
    • とはいえ、通常は可能性から考えると「(頭が赤い魚)を(食べる猫)」か「(頭が赤い)(魚を食べる猫)」のどちらかの解釈だとは思うのですが。
  • 長文を書くと曖昧な文章になりやすくなります。
    • ある程度長くなった場合には、いったん文を終端できないか考えてみてください。

主語を明らかにする

  • 主語を省くと、読み手に対して暗黙の主語を推測させることになります。
  • 状況によっては複数の解釈が生まれるので、誰がやっても結果が変わらない場合を除いて、主語を書きます。
    • ×「持ち込まれたパソコンが故障していると判断したので、修理依頼を出しました」(誰がなにをしているのかわからない)
    • ○「お客様が持ち込んだパソコンですが、カスタマーセンターで故障を確認したので、センター側で本部に修理依頼を出しました」
  • 指示語(こそあど言葉)をなるべく避けて、なにについて言及しているのか明確にします。
    • ×「Pythonは近年人気でAI分野でも広く使われる言語です。その理由は～」(その理由がどこにかかるのかわからない)
    • ○「Pythonは近年人気でAI分野でも広く使われる言語です。人気の理由は～」
    • ○「Pythonは近年人気でAI分野でも広く使われる言語です。AI分野で広く使われる理由は～」

略語・専門用語を避ける

  • 使おうとしている言葉が特定の文脈に強く依存していないか確認しましょう。
    • ×「DL」→○「ダウンロード」
    • ×「アドレス」「メルアド」→○「メールアドレス」
  • 名詞・固有名詞は略さず正確な表現を使います。また、必要でない限り商標を避けます。
    • ×「インフラ」→○「インフラストラクチャ」
    • ×「ホッチキス」→○「ステイプラー」
  • 正式名称に勝る表現がある場合には、例外的に優先して使用します。
    • ×「コンパクトディスク」→○「CD」
  • 一般的でない言葉や複数の解釈が生まれる言葉は定義してから使うようにします。
    • ×「弊社のハイパーデータベーステクノロジーでは～」
    • ○「弊社のフルマネージド型データベース管理システムのハイパーデータベーステクノロジーでは～」
    • ○「コンピュータサイエンス(CS)の分野では～」
    • ○「カスタマーサクセス(CS)向上のために～」

受身形を避ける

  • 文章の基本は能動形です。
    • △「機械語はソースコードからコンパイルされます」(受身)
    • △「ソースコードは機械語にコンパイルされます」(受身)
    • ○「ソースコードを機械語にコンパイルします」(能動)
  • 強調したい言葉によっては受身形を使うこともありますが、能動形のほうが理解しやすくなります。
  • 能動形で不自然になる表現は受身形のままで構いません。
    • ×「ベル研究所でC言語を開発しました」(能動)
    • △「ベル研究所でC言語は開発されました」(受身)
    • ○「C言語はベル研究所で開発されました」(受身)
    • ○「デニス・リッチーが主体となり、C言語を開発しました」(能動)
    • ○「デニス・リッチーが主体となり、C言語は開発されました」(受身)

二重否定を避ける

  • 否定の否定は論理的に捉えにくくなる上に、口語的表現なので避けます。
    • ×「JavaScriptが関数型言語でないとは言い切れない」
    • ○「JavaScriptは関数型言語であると言うこともできる」
  • 二重否定の文章を肯定形にした結果が論理的に正しいかは必ず検証してください。

感覚的な表現を避ける

  • 「非常」や「かなり」などは主観に基づく表現です。
  • 絶対的な基準を提示します。
    • ×「残量が残りわずかになると～」
    • ○「残量が5%を下回ると～」
    • ×「致命的な不具合が発生し～」
    • ○「不具合によってCPU使用率が100%になり、バッテリー消費が～」
  • あるいは比較対象を提示して、解釈に違いが生じにくくします。
    • ×「非常に多いアクセスがあり～」
    • ○「通常よりも多いアクセスがあり～」
    • ○「通常時の約100万ページビュー/日の10倍近いアクセスがあり～」

相応しい表現を選ぶ

  • 似ていても意味が異なる言葉があるので、文脈に相応しいものを使います。
    • 「文書を修正した」(誤りを直した)
    • 「文書を訂正した」(誤りを直して正しい表現にした)
    • 「文書を更新した」(なにかしら書き換えた)
    • 「文書を改訂した」(なにかしら書き換えて新しい版を出した)

手順や選択肢を提示する際は箇条書きにする

  • 必ずしも文章で表現する必要はありません。手順や選択肢は項目として列挙することで読み手が理解しやすくなります。
    1. 画面左上の[ファイル]を選択します。
    2. [ファイルを開く…]を選択すると、選択用ダイアログが表示されるので、アップロードしたいファイルを選択してください。
  • 箇条書きの中で過度に敬語を使用すると、内容が不明瞭になりやすいので避けます。

敬語を正しく使う

  • 自他の区別をしましょう。
    • ○「連絡いたします」(自分が連絡する)
    • ×「ご連絡いたします」(自分が連絡する)
    • ○「ご連絡ありがとうございます」(相手が連絡する)
  • 適切な度合いを見極めます。
    • △「お見積もりのご依頼をいただき～」
    • ○「お見積もりの依頼をいただき～」
    • ○「見積もりのご依頼をいただき～」

漢字の使い方

漢字で書く言葉・書かない言葉

  • 補助動詞は基本的にひらがなで表記します。
    • ×「～致します」→○「～いたします」
    • ×「～下さい」→○「～ください」
  • 読ませ方の違いで漢字で書くかどうか変わります。
    • 「～やその他(た)サービスを妨害する行為」「そのほか、弊社が〇〇と判断した～」
    • 「ニンジンやカボチャ等(とう)の緑黄色野菜は～」「ニンジンやカボチャなどの緑黄色野菜は～」
      • 「等」と「など」は同じように使えますが、正式な文章では「等」を用いることが多いようです。
    • 「決済時(じ)にメールを送信します」「エラーが発生したときは～」

送り仮名

  • 熟語には「置き換え」「置換え」「置換」のように複数の送り仮名の付け方があります。
  • 基本的には最後の漢字にのみ送り仮名をつけるようにします。
    • ○「プリンター複合機の置換えを予定しています」
    • △「プリンター複合機の置換を予定しています」(ちかんと読める)
  • ただし、読み間違いのないものに関しては、まったく送り仮名をつけないことも許容されます。
    • ○「前払にて承ります」
    • ○「受渡日の設定をしてください」

各種表現

AまたはB, AもしくはB

  • OR条件を表現するものです。複数ある場合には、A, BまたはCの形式をとります。
    • ○「CまたはC++で開発経験のある方」(C || C++)
    • ○「C, C++またはObjective-Cで開発経験のある方」(C || C++ || Objective-C)
  • 「もしくは」は小括弧の接続に、「または」は大括弧の接続に使用します。
    • ○「Pythonの開発経験または機械学習もしくはAI開発の実績のある方」(Python || (機械学習 || AI開発))

AおよびB, AならびにB

  • AND条件を表現するものです。複数ある場合には、A, BおよびCの形式をとります。
    • ○「CおよびC++で開発経験のある方」(C && C++)
    • ○「C, C++およびObjective-Cで開発経験のある方」(C && C++ && Objective-C)
  • 「および」は小括弧の接続に、「ならびに」は大括弧の接続に使用します。
    • ○「Pythonの開発経験ならびに機械学習およびAI開発の実績のある方」(Python && (機械学習 && AI開発))
  • 列挙するものがふたつの場合は「AとB」と言い換えられないか考えてみてください。
    • ○「CとC++による開発経験がある方」(C && C++)

場合・とき・際

  • 「場合」は大前提で「とき」は「場合」の中の小前提として使用します。
    • 「名前が未設定の場合、ニックネームも未設定のときはNullReferenceExceptionが発生します」
  • 「場合」は条件・状況・可能性として使用できる便利な言葉なので注意して使いましょう。
  • 具体的に表現することを意識して、なるべく「場合」を使わないようにするといいでしょう。
    • ×「Windowsを利用している場合には、非常に短い間隔で現在時刻を取得した場合に、同じ値が返される場合があります」
    • ○「Windowsでは分解能が大きいので、非常に短い間隔で現在時刻を取得した際に、同じ値が返される可能性があります」
  • 補足を入れたり別の表現にしたりすると「場合」を避けやすくなります。
  • 「際」はほかの2つよりも状況を示している度合いが強いように感じられます。

～こと

  • 「～こと」も「場合」のように便利な表現のひとつです。コトコトしすぎていないか意識しましょう。
    • ×「喫煙することは、健康リスクが上昇することに繋がります」
    • ○「喫煙は、健康リスクの上昇に繋がります」
  • 「～こと」を避けるとそっけない文章になりがちなので、必ずしも「～こと」の使用が悪とは言えませんが、「～こと」に依存しない文章を書けるようにしましょう。

〇〇しづらい、〇〇しにくい

  • 「～づらい」は主に主観的な困難や抵抗があるときに使用します。
    • 「私としては彼に頼みづらい」(なにか彼に対して抵抗感を抱いている)
    • 「～がたい」も主観で物事を主張するときに使われることが多いようです。
  • 「～にくい」は主に客観的な困難や抵抗があるときに使用します。
    • 「データ依存でエラーが発生したとは考えにくい」

〇〇や〇〇

  • 同グループの概念が3つ以上あることを示唆している表現です。
    • 「キュウリやナス」(キュウリやナスだけでなく、トマトやトウモロコシがあるかもしれない)
  • 2つちょうどであれば「キュウリとナス」で十分です。
  • 思いつくものが1つしかないときに「キュウリ等」と表現することは悪手です。
    • なんとかしてもうひとつ絞り出すか、「キュウリは～」と言い切ります。

〇〇たり、〇〇たり

  • 誤用の多い表現です。ひとつだけでは成立せず、似た概念にあるふたつ以上の言葉が必要です。
    • ×「休日は飲んだりしている」
    • ○「休日は食べたり飲んだりしている」

括弧の多用

  • 括弧は言葉の意味を補足するほか、略称を説明する役目を持つものであり、文章上自然に表現できるのであれば、括弧は不要です。
    • ○「コンテンツ配信ネットワーク(Contents Delivery Network: CDN)」
    • ○「ユーザーが20歳以上(≒大人)であれば、飲酒できます」
  • 括弧を多用するとラップの合いの手になりやすいです。
    • ×「ほとんどの人は〇〇したことがないと思います(もしあれば自慢しよう！)」
    • ○「ほとんどの人は〇〇したことがないと思うので、もしあれば自慢できます」
    • ×「これが世帯年収のグラフです(単位は万円)」
    • ○「これが世帯年収のグラフです」(単位が万円であることは図中で示す)
    • ×「0または1で結果が得られます(正確にはboolean)」
    • ○「結果は0をfalse, 1をtrueとした真偽値で得られます」

マークアップやハイライトを前提としない

  • 文章はプレゼンテーションとは異なります。
  • 太字や下線、色付き文字の使用は、文章の理解のしやすさには寄与しません。
    • 主張したい箇所を太字にしたり、下線をつけたりするのは無意味です。
    • 筆者だけが持つ暗黙知を形式知として書き起こして、読み手に誤解なく主張を伝えなければなりません。

詭弁

本来は話術に分類されるべきものですが、文章でも相手への反論として詭弁が使われることがあります。なにかしらの反論をしたいときには有効な手段ですが、問題を解決するどころか、却ってややこしくするだけのものなので避けた方が無難です。

しかし、いくつかの詭弁を覚えておくことで、詭弁を使ってくる相手への対処もしやすくなります。

論点のすり替え

  • 相手の不備や思考の隙を突いて、自分を優位にしようとするものです。
    • 技術者のAとBがいて、BがAをなんらかの方法で否定したい場合の一幕です。
    • A「CやC++と異なり、Rustでは即値に対しても参照が取れます」
    • B「それってなにか出典とかありますか？あなたの個人的な意見ですよね？」
    • ここではAが出典を提示しなかった落ち度はあるものの、「即値に対して参照が取れる」ことの正確さが重要なのであって、出典の有無や主観は関係ありません。
  • 「あいつだって」もよくみられます。
    • A「あなたは不正な操作を繰り返し行い、当社に損害を与えました。よって弁償を要求します」
    • B「ほかの人だってやっていますし、私だけが悪いわけではありません」
    • ここではAはBに対して論じているのであって、ほかの人は関係ありません。
  • 可能性が低いか、限られた状況を引き合いにだすこともあります。
    • A「リンゴは果物の中でも有名なもののひとつで、赤くて丸い形をしています」
    • B「青いリンゴもありますよ」

ストローマン

  • 相手の主張を歪めて、自分に有利な主張を繰り出すものです。論点のすり替えに分類されることもあります。
    • A「最近ではプログラミング初心者にC言語はオススメできません」
    • B「そうは思いません。C言語でメモリ管理や低級な操作を学ぶことによって、コンピュータの動作を理解しやすくなります。Aさんは基礎を飛ばしてPythonのような金儲けにすぐ繋がるような言語を学ぶべきだと主張していますが、それは正しいのでしょうか？」

感情や同情に訴えかける方法

  • 感情に訴えかける方法もあります。
    • A「明日は雨が降ると嬉しいのですが」
    • B「先日、大雨でX市に災害が起きましたが、同じことが起きて欲しいというのでしょうか？ひどくはありませんか？」
    • 配慮が足りないという状況もあり得ますが、相手が主張していないことに対して言及するのはよくありません。
  • 立場と役割の混同をしないようにします。
    • A「万引き程度で子供の未来を終わらせようとするのは言語道断である」
    • 万引きをしたという立場と、子供という役割は別の話です。法に照らし合わせて適切に裁かれなければなりません。

誤った二分法

  • 相手にYesかNoの二者択一を迫るものです。
    • 「Aさんは増税に賛成の立場ですか？それとも反対の立場ですか？」
    • 「ウンコ味のカレーとカレー味のウンコ、どちらを食べますか？」
  • 前提条件なしでは回答できないことに関して選択を迫ります。
    • これによって相手の主張の選択肢を狭めることができます。
    • どちらの回答をしたとしても、その極端な主張の穴を指摘して優位に立つ方法です。
  • 香西秀信氏は自著「レトリックと詭弁」の中で、「問いは、作った方が優位に立てる」と論じています。
    • 「答える側は、問われたことに答えなければなりません」
  • いっぽうで、のらりくらりと質問を躱し、結論を出さない相手に対して二分法は有効な手段です。
    • A「車のエンジンがかからないの…」
    • B「あらら？バッテリーかな？ライトは点く？」
    • A「昨日まではちゃんと動いてたのに。なんでいきなり動かなくなっちゃうんだろう」
    • B「トラブルって怖いよね。で、バッテリーかどうか知りたいんだけどライトは点く？」

技術文書の場合

結論を先に書いて、理由や裏付けを後に書く

  • 物語を書くことを要求されているわけではありません。
    • 求められていることに対して素早く結論を提示します。
    • 起承転結も必要ありません。
  • 結論を先に書いて、あとからそれを説明する文章を付け足していきます。
    • ×「HTMLやCSSと協調動作するプログラミング言語のひとつにJavaScriptがあります」
    • ○「JavaScriptはプログラミング言語のひとつです。主な特徴としてHTMLやCSSと協調動作して～」
    • ×「標準ライセンス約款中の記載により、Javaでは核、ミサイル、生物化学兵器もしくは原子力に関連した製品を開発することは禁止されています」
    • ○「Javaを使って核・原子力に関連する製品を開発することは禁止されています。これは約款中に～」

可能性の度合いを表す

  • 確実性・再現性の有無によって事象の度合いを正しく表現します。
  • 断定できる場合の表現には次のようなものがあります。
    • 「～は〇〇です」「～は〇〇できません」
  • 断定できない場合の表現には次のようなものがあります。
    • 「～ことがある」「～の可能性がある」「～という事実は確認できていません」

Discussion