Writing specification of Chinese technical documents

The title

The hierarchy

Headings are divided into four levels.

  • Level 1 heading: The title of the article
  • Secondary heading: The main heading of the main part of the essay
  • Tertiary headings: Sub-headings at one level below secondary headings
  • 4 headings: Sub-headings in one area under a 3 heading

Here’s an example.

# Level 1 title

## Secondary title

###

####
Copy the code

The principle of

(1) Under first-level headings, third-level headings cannot appear directly.

Example: The following article structure, missing secondary headings.

# Level 1 title

###
Copy the code

(2) The title should avoid isolated numbering (that is, there is only one title at the same level).

Example: In the following article structure, level 2 heading A contains only one level 3 heading. Level 3 heading A can be omitted entirely.

A

### A

B
Copy the code

(3) Sub-headings do not repeat the name of the title at the upper level.

Example: The following article structure, secondary title and subordinate tertiary title of the same name, recommended to avoid.

Summary of # #

Summary of # # #
Copy the code

(4) Carefully use four-level titles, avoid appearing as far as possible, keep the hierarchy simple, and prevent overly complicated chapters.

If there is parallelism under a tertiary heading, it is recommended to use only an Item list.

Example: Structure 2 below is better than structure 1. Structure 1 is suitable for scenes, mainly for longer content.

Structure of a###

#### 4

#### 4

#### 4Structure of the two###

** (1) A**

** (2) B**

** (3) C**
Copy the code

The text

Space between words

(1) There should be a space between full Chinese characters and full English characters.

Error: This article describes how to quickly start Windows. Correct: This article explains how to quickly start Windows.Copy the code

(2) There is no space between full-corner Chinese characters and half-corner Arabic numerals, but the style must be uniform and the two styles cannot be mixed.

Correct: On May 15, 2011, I ordered 5 laptops and 10 tablets. Correct: On May 15, 2011, I ordered 5 laptops and 10 tablets.Copy the code

The percent sign of the half Angle is regarded as Arabic numerals.

True: Our economy will grow at 6.5 percent this year. True: Our economy will grow at 6.5 percent this year.Copy the code

(3) If English units are not translated, proper space should be left between Arabic numerals and unit symbols in front of units.

Example 1: A smart phone with 16 GB capacity 2:1 h = 60 min = 3,600 sCopy the code

(4) English characters and Arabic numerals should not be separated from full punctuation marks.

Wrong: His computer is a MacBook Air. Right: His computer is a MacBook Air.Copy the code

The sentence

(1) Avoid long sentences.

Individual sentences that do not contain any punctuation marks, or sentence elements separated by commas, should be no more than 20 words in length; 20 ~ 29 words sentence, acceptable; 30 ~ 39 words sentence, semantic must be clear, to accept; Sentences of more than 40 words are not acceptable under any circumstances.

Error: This product is suitable for architectures ranging from single-node architectures with action controlled by a single server to parallel processor architectures with action controlled by multiple servers. True: This product is suitable for a variety of architectures. This product can be used whether it is controlled by one server (single node structure) or by multiple servers (parallel processing structure).Copy the code

Comma-separated sentences should be no longer than 100 words or 3 lines of text.

(2) Try to use simple sentences and compound sentences, avoid compound sentences.

He was ill yesterday and didn't attend the meeting. The man who was sick yesterday didn't attend the meeting.Copy the code

(3) The same meaning, try to use positive sentence expression, do not use negative sentence expression.

Error: Please make sure the device is not powered on. Correct: Make sure the device is powered off.Copy the code

(4) Avoid using double negatives.

Error: Users without delete permission cannot delete this file. Correct: The user must have delete permission to delete this file.Copy the code

Writing style

(1) Use the active voice instead of the passive voice.

Error: The software has not been installed, true: The software has not been installed,Copy the code

(2) Do not use informal language style.

Wrong: Lady Gaga's concert was so cool, never seen such a powerful performance!! Correct: I regret not being able to attend this event.Copy the code

(3) Don’t use cold, invented or classical Chinese words, but use common expressions in modern Chinese.

Wrong: This is the only fast start method. True: These are the only two ways to get a fast start.Copy the code

(4) Use the right words.

She smiled happily. She smiled happily. (adverb + place + verb) She had a good laugh. (verb + get + adverb)Copy the code

(5) When using pronouns (such as “he”, “he”, “this”, “this”, etc.), it must be clear that the content of the reference, ensure that there is only one meaning.

Error: The slave management system can monitor the relay system and the distribution system under its direct control. True: The slave management system can monitor two systems: a relay system and a distribution system directly controlled by the relay system.Copy the code

(6) Don’t use too many adjectives in front of nouns.

Error: This equipment must be used under the direction of a technician who has received formal equipment training from our company. Correct: this equipment must be used under the supervision of a technician who has received formal equipment training organized by our company.Copy the code

English to deal with

(1) If the plural form is used in the Original English text, it should be restored to the singular form when translated into Chinese.

英文 : information stored in random access memory (RAMs)... Information stored in random access memory (RAM)...Copy the code

(2) Foreign abbreviations can use half corner dot (.) Stands for abbreviation.

U.S.A.
Apple, Inc.
Copy the code

(3) When denoting Chinese, English ellipsis (…) should be changed to Chinese ellipsis (…). .

英文 : five minutes later...Copy the code

(4) When the English title or movie title is expressed in Chinese, the double quotation marks should be replaced by the book title.

English: He published an article entitled "The Future of The Aviation". English: He published an article entitled "The Future of Aviation".Copy the code

(5) When English words appear for the first time, give Chinese marks in brackets. When it comes up again, just use the English abbreviation.

IOC (International Olympic Committee) With this definition, "IOC" can be used directly.Copy the code

(6) The first letter of each word should be capitalized in proper nouns, but not in non-proper nouns.

Capitalize the American Association of Physicists in Medicine "Online Transaction processing" is not a proper noun and should not be capitalized.Copy the code

The paragraph

The principle of

  • A paragraph can have only one topic, or one central sentence.
  • Put the central sentence at the beginning of the paragraph, giving a summary of what the paragraph is about. The following statements serve the core sentence.
  • A paragraph should be no longer than seven lines. The best paragraph length should be no more than four lines.
  • Use declarative and positive sentences in paragraphs, avoid exclamatory sentences.
  • Separate paragraphs with a blank line.
  • Do not leave white space at the beginning of a paragraph.

reference

When quoting third-party content, the source shall be indicated.

One man's constant is another man's variable. -- Alan PerlisCopy the code

If reprinted in full, please indicate the author and source prominently at the beginning of the full text and link to the original text.

This article is reprinted from WikiQuoteCopy the code

When using external images, the source must be identified below or at the end of the text.

Some of the images are from WikipediaCopy the code

The numerical

Half Angle of digital

All Arabic numerals should be in half – corner form, not full – corner form.

Wrong: The price of this product is 1000 yuan. Correct: The price of this item is 1000 yuan.Copy the code

QianFenHao

If the value is more than thousands, add a semicolon (semicolon).

The paid-in capital of XXX company is RMB 1,258,000.Copy the code

For numbers up to 4 digits, the semicolon is optional; for example, 1000 and 1,000 are acceptable. For values above 4 digits, a semicolon is required.

currency

The currency should be in Arabic numerals and be preceded by the currency symbol or followed by the Chinese name of the currency.

$1000 to $1000Copy the code

For the English currency name, please refer to the international standard ISO 4217.

Numerical range

To indicate a range of values, use a ~ or — connection. See join in the punctuation section.

When there are units or percent signs, it is recommended to add units or percent signs to both numbers.

132kg to 234kg 67% to 89%Copy the code

A representation of the degree of change

Use the words “increased” and “increased to” to increase numbers. “Up” means incremental, and “up” means quantitative.

Twice as much as it used to be, now it is three times as much as it was oneCopy the code

To reduce a number, use “reduced”, “reduced to”. “Up” means incremental, and “up” means quantitative.

Reduced to 80% (quota is one hundred, now it is eighty) reduced to 80% (it was one hundred, now it is twenty)Copy the code

Do not use the notation “decrease by N times” or “decrease by N times”, use “decrease by a few percent” or “decrease by a few percent”. Because decreasing (or decreasing) by twice means that the value, which was a hundred, is now equal to zero.

punctuation

The principle of

(1) Punctuation marks of Chinese sentences should adopt full-angle symbols, so as to maintain visual consistency with full-angle characters.

(2) If the whole sentence is in English, use English/half-corner punctuation.

(3) Periods, question marks, exclamation marks, commas, stops, semicolons and colons may not appear at the beginning of a line.

(4) Periods (periods, commas, periods, semicolons, colons) may not appear at the end of headings, while labels (quotation marks, parentheses, dashes, ellipses, marks, emphasis, interspaces, exclamation points, question marks) may.

An end

(1) A full period should be used at the end of a Chinese sentence. .

(2) When parentheses are used at the end of a sentence, the full stop should be outside the parentheses.

Error: For the output of the file, see section 1.3 (see page 26). True: for output of the file, see section 1.3 (see page 26).Copy the code

The comma

(1) Comma (,) indicates a general pause inside a sentence.

(2) Be careful not to use commas in all of your paragraphs except at the end.

pause

(1) We should use a comma (,) to separate the words in the sentence, even if the words are In English.

Wrong: My favorite tech companies are Google, Facebook, Tencent, Alibaba, Baidu, etc. Right: My favorite tech companies are Google, Facebook, Tencent, Alibaba and Baidu.Copy the code

(2) In English sentences, half corner comma (,) is used to separate parallel words.

Example: Microsoft Office includes Word, Excel, PowerPoint, Outlook and other components.Copy the code

(3) Use (and) to connect the last one to make the sentence read more coherent. The following two sentences can be used, the second is better.

Right: My favorite tech companies are Google, Facebook, Tencent, Alibaba, baidu, etc. Right: My favorite tech companies are Google, Facebook, Tencent, Alibaba and Baidu.Copy the code

A semicolon

(1) semi-colon (;) Denotes a pause between compound clauses within a complex sentence.

quotes

(1) When quoting, use full-angle double quotation marks (” “). Note that the double quotation marks are different.

Ex: Many people believe that the core of customer service is "friendly" and "professional".Copy the code

(2) If you need to use quotation marks inside the quotation marks, use double quotation marks on the outer layer and single quotation marks on the inner layer.

Ex: "I wanted to play music, but Sally said, 'No way! '."Copy the code

parentheses

(1) For supplementary statements, use full-angle parentheses (()) without Spaces before or after the parentheses.

Example: Make sure all connections (cables and connectors) are securely installed.Copy the code

(2) Chinese and English names of several parentheses.

English Chinese
{} Braces or curly brackets Curly braces
[] Square brackets or brackets The square brackets
< > angled brackets Angle brackets
( ) parentheses parentheses

The colon

(1) the full colon (:) is often used after words that require explanation.

Example: Please confirm the following: time, place, event name and number of guests.Copy the code

(2) for time, use semicolons (:).

Example: 8:00 a.mCopy the code

ellipsis

(1) Ellipsis (……) Indicates an unfinished statement or a discontinuity of tone.

(2) The ellipsis takes up two Chinese characters and contains six ellipsis points. Do not use… Or… And other non-standard forms.

(3) Ellipsis should not be used with the word “etc.”

Wrong: We have bananas, apples, pears... And other colorful fruits. Correct: We prepared colorful fruits for the dinner, bananas, apples, pears... Correct: we prepared bananas, apples, pears and other colorful fruits for the dinner.Copy the code

Exclamation mark

(1) Use a calm tone and avoid exclamation marks (!). .

(2) Do not use multiple exclamation points, such as!! And!!!!!! .

Dashes.

(1) The dash ———— is commonly used for further explanation.

(2) The dash should occupy the space between two Chinese characters. If the dash itself takes up only one character, a half-corner space should be left before and after it.

Ex: Intuition ———— although it is not always reliable ———— tells me that something might be wrong. Ex: Intuition, though not always reliable, tells me that something might be wrong.Copy the code

connective

(1) Join signs are used to join two similar words.

(2) In the following cases, a straight line connector (-) should be used, occupying one half of the space of a character.

  • A compound of two nouns
  • The chart number
Example: oxidation - reduction reaction Example: Figure 1-1Copy the code

(3) Numeric ranges (such as date, time, or number) should use a wave connector (~) in the position of a full-corner character.

Example: From 2009 to 2011Copy the code

Note that units should be added to both values before and after the wave sign.

(4) The wave connector can also be replaced by the Chinese character “To”.

Example: Ambient temperature: -20°C to -10°CCopy the code

Document system

structure

The software Manual is a complete book and the following structure is recommended.

  • The document provides a general, concise description of the product and the document itself
  • Getting Started: [Optional] [file] How to use the product most quickly
  • Introductory articleBasics, Basics, Basics, Basics, Basics, Basics
    • Environmental preparation: [Prerequisite] [document] Prerequisites to be met for using software
    • Installation: [Optional] [file] Method of installing software
    • Configuration: [Required] [file] Software Settings
  • Advanced: [Optional] [directory] also known as “development”, provides intermediate and Advanced development tutorials
  • API (Reference) : [optional] [directory | file] software API introduced
  • FAQ: [Optional] [File] Frequently asked Questions
  • The appendixAppendix: Something that is not part of the tutorial itself, but that will help you read it
    • Glossary: [optional] [document] noun explanation
    • Recipes: [Optional] [file] Best practices
    • Troubleshooting: [Optional] [file] Troubleshooting
    • ChangeLog: [Optional] [File] Version description
    • Feedback: [Optional] [file] Feedback mode

Here are two real examples to consider.

  • Story book
  • Manual of the Atom

The file name

The file name of the document must not contain Spaces.

The file name must contain half-corner characters, not full-corner characters. This also means that Chinese cannot be used for file names.

Incorrect: noun explanation md correct: glossary.mdCopy the code

You are advised to use only lowercase letters in the file name.

Error: TroubleShooting. Md Correct: TroubleShooting. MdCopy the code

To stand out, you can use uppercase letters to describe file names, such as README and LICENSE.

If a file name contains multiple words, separate them by hyphens (-).

Bad: advanced_usage.md Correct: advanced-usage.mdCopy the code

Refer to the link

  • Product manual Written specifications in Chinese, by Huawei
  • Write specifications and format specifications by DaoCloud
  • The Application of Technical Writing techniques in Japanese-Chinese Translation, by Liu Fang
  • Guide to the Simplified Chinese Language Specification, by Lengoo
  • Document Style Guide, by LeanCloud
  • A Copy Style Guide by Pea Pod
  • Chinese text typesetting refers to north, by Sparanoid
  • Chinese typesetting requirements, by W3C
  • Why should file names be lowercase? , by Nguyen Yifeng
  • Google Developer Documentation Style Guide, by Google
  • Provisions on the Use of Numbers in Publications (National Standard GBT15835-2011)
  • Digital usage of national Standard publications of the People’s Republic of China
  • International system of units and its application

Original address: github.com/ruanyf/docu…

Author: Ruan Yifeng