Some Simple Rules for English Technical Writing

Lexical Rules

1. Use articles（冠词）, "the", "a", and "an", before singulars（名词的单数形式）, if there is not adherent adjunct before the noun. No articles for plurals（名词的复数形式）.

   For example, the following are alright:

   • Do you have a computer?
   • I don't need an expensive computer.
   • I don't need expensive computers.
   • That is the expensive computer you mentioned.

2. Underscore (_) is not part of English words or phrases. We usually use underscores in source code, e.g., variable names. In such cases, we follow Markdown syntax to quote a variable name with a back single quote (`).

   The following are alright:

   • model_def
   • the model definition

3. Some typical cases to use, or not to use, the dash (-):

   • a tf.keras.Model-derived class
   • a four-dimensional tensor
   • a 3-year old girl
   • a 3 years old girl

4. Spell proper nouns（专有名词） as its conventional form. For example, TensorFlow but not Tensorflow, PyTorch but not Pytorch or py-torch, and ElasticDL but not elasticdl or elastic-dl.

Grammar Rules

1. Use short sentences over long ones.
2. Use clauses only when it is necessary.
3. Use active voice other than passive voice.