The Basics of English Technical Writing

1. クリアな文章で

あいまいな代名詞はつかわない

• 必ずそれを指す名詞を出した後の文に入れる（it, them など）
• できるだけ参照する名詞に置く。もし指す名詞との間に 5 単語あれば、代名詞を使わずにその名詞をそのまま書くこと
• “it / they, them, and their” が一番混乱しやすい代名詞！
• “this /that”も混乱しやすいので、参照する名詞のすぐ後につける or 名詞をそのまま書く

（例）どちら（どれ）を指してるかわかりにくい文例 Python is interpreted, while C++ is compiled. It has an almost cult-like following. → Python？C++?どっち？ Be careful when using Frambus or Carambola with HoobyScooby or BoiseFram because a bug in their core may cause accidental mass unfriending. Running the process configures permissions and generates a user ID. This lets users authenticate to the app. → 2 文目の提案例：This user ID lets users authenticate. / The process of configuring permissions lets users authenticate. / The combination of permissions and a user ID lets users authenticate.

<Exercise> 　次の文章で下線の代名詞が指してる可能性がある単語はどれでしょうか。（複数）

Aparna and Phil share responsibilities with Maysam and Karan and they are next on call. You may import Carambola data via your configuration file or dynamically at run time. This may be a security risk.

The pronoun they could refer to any of the following:

• Aparna and Phil
• Maysam and Karan
• Aparna, Phil, Maysam, and Karan
• Any one of the individuals as a singular gender-neutral pronoun

The pronoun this could refer to any of the following:

• Importing via the configuration file
• Importing dynamically at run time
• Both

できるだけ能動態をつかう

• 基本、能動態をつかう ー主語をはっきりさせる
• 命令形には受動態（受け身）は使わない
• 能動態の利点とは？
  • 文書を読むとき、人は受動態を自然と能動態に訳している。その時間をセーブすることができる。
  • 受動態だと読む手に考えがストレートに伝わらない。受動態は遠回しに言いたい時にはいい。
  • 受動態だと関係者がわからず（主語の大半がモノのため）、読み手に関係者が誰かを想定させてしまう。
  • 受動態よりも文が短くできる＝より簡潔◎

<Exercise> 次の文章を能動態にしましょう。

The flags weren’t parsed by the Mungifier. A wrapper is generated by the Op registration process. Only one experiment per layer is selected by the Frombus system. Quality metrics are identified by asterisks; ampersands identify bad metrics.

The Mungifier didn’t parse the flags. The Op registration process generates a wrapper. The Frombus system selects only one experiment per layer. Asterisks identify quality metrics; ampersands identify bad metrics.

強い動詞を使う（わかりやすい）

• 弱い動詞例：“be 動詞、occur、happen など→ ぼんやりしている

NG: The error occurs when clicking the Submit button. OK: Clicking the Submit button triggers the error.

NG: This error message happens when.. OK: The system generates this error message when…

NG: We are very careful to ensure… OK: We carefully ensure…

<Exercise> 次の文章をもっと強い動詞を使って書き換えましょう。

When a variable declaration doesn’t have a datatype, a compiler error happens. Compiler errors occur when you leave off a semicolon at the end of a statement.

When a variable declaration doesn’t specify a datatype, the compiler generates an error message. A missing semicolon at the end of a statement triggers compiler errors.

There is / are はできるだけ使わない

• There is / are の 代わりに別の 1 語か 2 語を主語にする

NG: There is a variable called met_trick that stores the current accuracy. OK: A variable named met_trick stores the current accuracy. / The met_trick variable stores the current accuracy.

NG: There are two disturbing facts about Perl you should know. OK: You should know two disturbing facts about Perl.

NG: There is no guarantee that the updates will be received in sequential order. OK: Clients might not receive the updates in sequential order.

<Exercise> 次の文章を There is を使わず書き直しましょう。

There is a lot of overlap between X and Y. There is no creator stack for the main thread. There is a low-level, TensorFlow, Python interface to load a saved model. There is a sharding function named distributedistribute that assigns keys.

X and Y overlap a lot. TensorFlow provides a low-level Python interface to load a saved model. TensorFlow provides a low-level Python interface to load a saved model. The distribute sharding function assigns keys.

2. 短い文章で

ひとつの文にひとつのアイデア

NG: The late 1950s was a key era for programming languages because IBM introduced Fortran in 1957 and John McCarthy introduced Lisp the following year, which gave programmers both an iterative way of solving problems and a recursive way. →１つの文章に複数のアイデアが存在

The late 1950s was a key era for programming languages. IBM introduced Fortran in 1957. John McCarthy invented Lisp the following year. Consequently, by the late 1950s, programmers could solve problems iteratively or recursively. →繋ぎ言葉などを使って短い文に

<Exercise> 次の文章を短い文に書き直しましょう。

In bash, use the if, then, and fi statements to implement a simple conditional branching block in which the if statement evaluates an expression, the then statement introduces a block of statements to run when the if expression is true, and the fi statement marks the end of the conditional branching block.

In bash, use an if, then, and fi statement to implement a simple conditional branching block. The if statement evaluates an expression. The then statement introduces a block of statements to run when the if expression is true. The fi statement marks the end of the conditional branching block. → 解答例の段落はまだ不明瞭なままではあるが、元の文章よりもかなり読みやすくなっている。

余分なものは入れない

読みやすく維持しやすく（コードを書く時と同じ！）

NG: An input value greater than 100 causes the triggering of logging. OK: An input value greater than 100 triggers logging.

NG: This design document provides a detailed description of Project Frambus. OK: This design document details Project Frambus.

（書き換え例）

くどい	簡潔
at this point in time	now
determine the location of	find
is able to	can

<Exercise> 次の文章を簡潔な語を使い書き直しましょう。

In spite of the fact that Arnold writes buggy code, he writes error-free documentation. Changing the sentence from passive voice to active voice enhances the clarification of the key points. Determine whether Rikona is able to write code in COBOL. Frambus causes the production of bugs, which will be chronicled in logs by the LogGenerator method.

Although Arnold writes buggy code, he writes error-free documentation. / Alternative answer: Arnold writes buggy code. However, he writes error-free documentation. Changing the sentence from passive voice to active voice clarifies the key points. Determine whether Rikona can code in COBOL. Frambus produces bugs, which the LogGenerator method logs.

that と which を使い分ける

• 基本的に関係代名詞の which は補足として使い省略可（カンマを前につけることができる, 直後に動詞が来る場合を除く）
• 関係代名詞の that は動詞を続ける時に使用（カンマは NG）する。that だと以下の節が省略できない

Python is an interpreted language, which Guido van Rossum invented.（which 以下は省略可） Fortran is perfect for mathematical calculations that don’t involve linear algebra.（that 以下は省略不可）

リストにする

順番のないものには記号で、順番があるものは番号で箇条書きする。

Bash provides the following string manipulation mechanisms:

• Deleting a substring from the start of a string
• Reading an entire file into one string variable

Take the following steps to reconfigure the server:

1. Stop the server.
2. Edit the configuration file.
3. Restart the server.

The llamacatcher API enables callers to create and query llamas, analyze alpacas, delete vicunas, and track dromedaries. ↓ The llamacatcher API enables callers to do the following:

• Create and query llamas.
• Analyze alpacas.
• Delete vicunas.
• Track dromedaries.

<Exercise> 次の文章を箇条書きにしてわかりやすく書き換えましょう。

Today at work, I have to code three unit tests, write a design document, and review Janet’s latest document. After work, I have to wash my car without using any water and then dry it without using any towels.

解答例１）

I must do the following at work today:

• Code three unit tests.
• Write a design document.
• Review Janet’s latest document.

After work, I must do the following:

1. Wash my car without using any water.
2. Dry my car without using any towels.

解答例２） I must do the following tasks today:

• At work:
  • Code three unit tests.
  • Write a design document.
  • Review Janet’s latest document.
• After work:
  • Wash my car without using any water.
  • Dry my car without using any towels.

3. 段落編：すばらしい書き出しで

はじめの一文が最重要！

• 読み手は最初の文しか読まない。（あとは飛ばし読みする）
• 良い文でスタートすると、文章のコアを作りやすくなる。

（例）最初の文がわかりにくく、読み手がわからなくなる文章 A block of code is any set of contiguous code within the same function. For example, suppose you wrote a block of code that detected whether an input line ended with a period. To evaluate a million input lines, create a loop that runs a million times.

（例）最初の文がよく、効果的な文章 A loop runs the same block of code multiple times. For example, suppose you wrote a block of code that detected whether an input line ended with a period. To evaluate a million input lines, create a loop that runs a million times.

<Exercise> 次の文章の書き出しは良い？良くない？その理由は？

The Pythagorean Theorem states that the sum of the squares of both legs of a right triangle is equal to the square of the hypotenuse. The k-means clustering algorithm relies on the Pythagorean Theorem to measure distances. By contrast, the k-median clustering algorithm relies on the Manhattan Distance.

良くない （理由） Clustering algorithms にフォーカスした文章なのに、書き出しのせいで Pythagorean Theorem にフォーカスしているように見える。 　良い書き出し例：Different clustering algorithms measure distances differently.

ひとつの段落に、ひとつのトピック

• ひとつの段落は独立したユニットである
• 現在に集中させるため、過去に起こったこと・未来のことは書かない。（改訂などあれば、その部分は削除する）

不要な文が入っている文章 The Pythagorean Theorem states that the sum of the squares of both legs of a right triangle is equal to the square of the hypotenuse. The perimeter of a triangle is equal to the sum of the three sides. You can use the Pythagorean Theorem to measure diagonal distances. For example, if you know the length and width of a ping-pong table, you can use the Pythagorean Theorem to determine the diagonal distance. To calculate the perimeter of the ping-pong table, sum the length and the width, and then multiply that sum by 2.

不要な文を削除した文章 The Pythagorean Theorem states that the sum of the squares of both legs of a right triangle is equal to the square of the hypotenuse. The perimeter of a triangle is equal to the sum of the three sides. You can use the Pythagorean Theorem to measure diagonal distances. For example, if you know the length and width of a ping-pong table, you can use the Pythagorean Theorem to determine the diagonal distance. To calculate the perimeter of the ping-pong table, sum the length and the width, and then multiply that sum by 2.

#+begin_quote <Exercise> 次の文章から不要な 1 文を削除しましょう。

Spreadsheets provide a great way to organize data. Think of a spreadsheet as a table with rows and columns. Spreadsheets also provide mathematical functions, such as means and standard deviations. Each row holds details about one entity. Each column holds details about a particular parameter. For example, you can create a spreadsheet to organize data about different trees. Each row would represent a different type of tree. Each column would represent a different characteristic, such as the tree’s height or the tree’s spread. #+end_quote>

.Spreadsheets provide a great way to organize data. Think of a spreadsheet as a table with rows and columns. Spreadsheets also provide mathematical functions, such as means and standard deviations. Each row holds details about one entity. Each column holds details about a particular parameter. For example, you can create a spreadsheet to organize data about different trees. Each row would represent a different type of tree. Each column would represent a different characteristic, such as the tree’s height or the tree’s spread.

長すぎず、短すぎず

• 長い文章＝威圧的にみえる
• １つの段落に 3~4 文くらいが一番読んでくれる。7文以上は無視される。
• 全段落が 1 文しかない場合、下の 3 つのネタを入れて 3~4 文くらいにする又は表にする。

What：何を伝えようとしているのか？ Why：なぜそれが読み手にとって重要か？ How：どう読み手はその知識をつかうのか？どうすれば読み手はそれが本当だとわかるのか？

（例）what / why / how をいれた文章

<Start of What>The garp() function returns the delta between a dataset’s mean and median.<End of What> <Start of Why>Many people believe unquestioningly that a mean always holds the truth. However, a mean is easily influenced by a few very large or very small data points.<End of Why> <Start of How>Call garp() to help determine whether a few very large or very small data points are influencing the mean too much. A relatively small garp is relatively high.<End of How>

4. 句読点編：カンマ (,) vs. セミコロン (;) vs. コロン (:)

カンマ (,)

• プログラミングにはカンマを付けるところが重要になるが、英文ではそれが不明瞭。
  • コツは・・・話す時に息をつくところに入れる C behaves as a mid-level language, just a couple of steps up in abstraction from assembly language.
  • いくつかの単語を並列する時 Our company uses C++, Python, Java, and JavaScript.）＊オックスフォードカンマは and の前にカンマは入れないが、テクニカルライティングではカンマをいれること。
  • 簡単な定義を追加するとき Python, an easy-to-use language, has gained significant momentum in recent years.
  • 二つの異なった文には使わない NG: Samantha is a wonderful coder, she writes abundant tests. OK: Samantha is a wonderful coder. She writes abundant tests.

<Exercise> 次の文章が読みやすくなるようにカンマを入れよう。

Protocol Buffers sometimes known as protobufs are our team’s main structured data format. Use Protocol Buffers to represent store and transfer structured data. Unlike XML Protocol Buffers are compiled. Consequently clients transmit Protocol Buffers efficiently which has led to rapid adoption.

Protocol Buffers, sometimes known as protobufs, are our team’s main structured data format. Use Protocol Buffers to represent, store, and transfer structured data. Unlike XML, Protocol Buffers are compiled. Consequently, clients transmit Protocol Buffers efficiently, which has led to rapid adoption.

セミコロン(;)

• ピリオド(.)は違う考えを分けるために使う。が、セミコロン(;)は非常に関連している考えを組み合わせて使う。
  • コツは・・・セミコロンの前後の文を入れ替えても、関連していることがきちんと通じていたら OK Rerun Frambus after updating your configuration file; don’t rerun Frambus after updating existing source code. ⇔ Don’t rerun Frambus after updating existing source code; rerun Frambus after updating your configuration file.
  • セミコロン(;)のあとは文章（S+V)にすること。 NG: Rerun Frambus after updating your configuration file; not after updating existing source code. OK: Rerun Frambus after updating your configuration file, not after updating existing source code. → カンマなら OK

コロン (:)

• コロンは (:) 密接に関連のあるものが続くときに使う。
• コロンの前は主語＋動詞があること
  • The fields are: …
  • The fields are defined as follows:
• コロンの後の頭文字は小文字にする
  • Tone: concise, conversational, friendly, respectful
  • When you add or update content to an existing project, remember to take these steps: review the style guide, use checklists, enlist a fellow writer or an editor to copyedit your work, and request a developmental edit if you feel that it’s warranted.

5. その他：ライティングのきほん

短縮系はつかわない

• ライティングのきほんの「き」

NG: The browser’s fast, simple, and secure. OK: The browser is fast, simple, and secure.

NG: The following guides’re a good way to learn to use Universal Analytics. OK: The following guides are a good way to learn to use Universal Analytics.

”If”は最初に置く

条件、目的は最初に置くこと

Recommended	Not Recommended
For more information, see [link to other document].	See [link to other document] for more information.
To delete the entire document, click Delete.	Click Delete if you want to delete the entire document.
If your app is located in one of the following regions, using custom domains might add noticeable latency to responses:	Using custom domains might add noticeable latency to responses if your app is located in one of the following regions:

現在形 vs. 未来形

• 突発的ではなく、一般的に起こることは現在形をつかう。 NG: Send a query to the service. The server will send an acknowledgment. OK: Send a query to the service. The server sends an acknowledgment.
• 未来に起こるアクションには未来形をつかう。 OK: Add the filename to the backup list. The file will be archived the next time the backup process runs.
• “would”はつかわない（仮定法になる） NG: You can send an unsubscribe message. The server would then remove you from the mailing list. OK: If you send an unsubscribe message, the server removes you from the mailing list.

6. 使っていい単語 vs. 使ってはいけない単語

Google for Developers Word List を参照してください。 https://developers.google.com/style/word-list