見出し画像

エンジニアが文章を書くときの細かいコツ

杉村勇馬

G-gen Tech Blogの文章

G-gen Tech Blog の記事は、全件、CTO がレビューしてから公開しています。その際に、細かい文言の修正をお願いすることもしばしばです。口うるさい私のレビューを受け続けた G-gen のエンジニアたちが次第に私の判断基準に寄せてくれていることもあり、G-gen Tech Blog の品質は概ね均一なものになっているように感じます。

当記事では、技術ブログ記事や、プロジェクトにおけるドキュメンテーション、顧客とのやりとりでエンジニアが書く文章について、私が気をつけていることをご紹介します。

「〜について」は省く

例えば Compute Engine の解説記事に「永続ディスクについて」という見出しがあれば、これは「永続ディスク」に修正します。「永続ディスク」という見出し名である時点で、この見出しが「永続ディスクについて書いているセクションである」ということは自明なので「〜について」は削除したほうが、見栄えがよくなります。

以下のように「〜について」がある場合とない場合を比べると、ない場合のほうがすっきりしていて、分かりやすいように思います。

「〜について」がある場合
「〜について」がない場合

時制を明確にする

日本語は、時制があいまいになりやすい言語です。時制は、特にサポート窓口や E メールでのビジネス上のやりとりで重要です。特に「〜しております。」「〜しています。」という表現には気をつけてください。

「その点につきましては、確認しております。」

この文章を見た時、調査は「今、確認している最中である」「確認が既に完了した」のどれでしょうか。口語の場合は、どちらの意味とも取れます。

ビジネス上のやりとりでは「確認しました。」「確認済みです。」あるいは「現在、確認中です。」のように、時制を明確にすることが望ましいです。

あいまいな言葉は避ける

実は先ほどの文章には、時制以外にもすこし危ない言葉が含まれています。それは「確認」です。「確認」はいくつもの意味を含んでいます。「（技術的な仕様について）確認中です」なら「今、調べています」の意味になりますし、「（メールが来たことを）確認しました」なら「（メールが来たことが）事実であることが確かめられました」という意味になります。

文脈から自明である場合もありますが、複数の意味を含む単語の使用には注意を払うべきです。以下は、IT の現場で使われがちなあいまいな言葉の例です。

  • 確認（調査する、有無を確かめる、真偽を確かめる…）

  • 連携（ファイルを転送する、API リクエストでデータを受け渡す、人の間で情報を共有する…）

  • 支援（請負で開発する、準委任で技術支援する、営業活動として支援する…）

見出し構成を階層化する

見出し構成（目次構成）は大見出し・中見出し・小見出しの最大3階層程度で階層化されているべきです。これ以上の階層化は、逆に読みづらくなります。また、階層化の粒度は揃っているべきです。

以下は、階層化されていない見出しです。同じ粒度の見出しが平坦に配置されており、意味のまとまりを掴みにくくなっています。

階層化されていない見出し


以下は、階層化が不揃いな見出しです。大見出しごとに異なる階層を持っているため、やはり読みづらくなります。

階層化が不揃いな見出し

以下は、適切に階層化された見出しです。同じ粒度の見出しが同じレベルの階層にまとまっており、文章のまとまりが把握しやすくなります。

階層化された見出し

文章は「概要から詳細」

記事全体で、文章を以下の流れにします。

  • 概要から詳細

  • 抽象から具体

はじめに概要的なことや抽象的な概念について説明し、次に詳細や具体的な内容を書きます。この順番を守ることが原則です。

ただし、まさに当記事のように、並列にものごとを列挙する記事もあります。当記事は以下のような構成になっています。

  1. 扉文

  2. 項目1

  3. 項目2

  4. 項目3…

このような記事では、はじめに頭文（リード文）を配置し、そのあと並列に項目を列挙します。項目の粒度（文量や詳細さ）を揃えることが大事です。

構成図は「上から下」「左から右」

構成図を書くときは、以下のような流れを守ります。

  • 上から下

  • 左から右

通信やデータ、業務の流れの矢印が「上から下」「左から右」になるようにします。

例外的に、クラウドが関係するインフラ構成図では「クラウドが上、オンプレが下」となる構成はよく見られます。

インプットとアウトプット

読みやすい文章やブログ記事を書けるようになるには、インプットとアウトプットの両方が必要です。「学びて思はざれば則ち罔（くら）し。思ひて学ばざれば則ち殆（あやう）し」という言葉がありますが、文章執筆の背景においては「インプットとアウトプットをバランスよく、両方やりましょう」と解釈することもでます。

技術書を読むエンジニアは多いと思います。しかし、技術書以外の本を頻繁に読むエンジニアは、思った以上に少ないです。技術書以外の本を読んで、自然科学と社会科学の背景知識を得ることで、文章に説得力が生まれるように思います。

この記事が気に入ったらサポートをしてみませんか？