Documentation Writing Guidelines

Thanks

This documentation writing guidelines is based on the guidelines from the Nitwikit project. Thanks to the contributors of the Nitwikit project.

1. Title Guidelines

Hierarchy Structure

• First-level heading: Article title
• Second-level heading: Main section titles
• Third-level heading: Subtitles under second-level headings
• Fourth-level heading: Avoid using as much as possible, keep the hierarchy simple

Usage Principles

1. Third-level headings cannot appear directly under first-level headings
2. Avoid isolated numbering (only one heading at the same level)
3. Subheadings should not repeat the name of the previous level heading
4. Use fourth-level headings cautiously, can be replaced by itemized lists

2. Paragraph Guidelines

Basic Principles

• One paragraph should have only one theme or central sentence
• The central sentence should be placed at the beginning of the paragraph, summarizing the entire paragraph
• Paragraph length should not exceed seven lines, optimal length ≤ four lines
• Use declarative and affirmative tone, avoid exclamatory tone
• Separate paragraphs with one blank line
• Do not leave blank characters at the beginning of paragraphs

Citation Guidelines

• When citing third-party content, indicate the source
• For full text reposts, indicate the author and source prominently at the beginning
• When using external images, indicate the source below the image or at the end of the text

3. Text Guidelines

Character Spacing

1. There should be a half-angle space between full-angle Chinese characters and half-angle English characters
2. The spacing style between full-angle Chinese characters and half-angle Arabic numerals should be consistent
3. Leave appropriate space between Arabic numerals and unit symbols before English units
4. No space between half-angle characters and full-angle punctuation marks

Sentence Guidelines

1. Avoid using long sentences (best within 20 characters, not exceeding 40 characters)
2. Try to use simple sentences and coordinate sentences, avoid complex sentences
3. Use affirmative expressions, do not use negative sentences
4. Avoid using double negatives

Writing Style

1. Use active voice, avoid passive voice
2. Use formal language style, avoid informal expressions
3. Use modern Chinese common expressions, avoid obscure, coined or classical Chinese words
4. Use "的", "地", "得" correctly
5. Pronoun references should be clear, ensuring only one meaning
6. Avoid using too many adjectives before nouns

English Handling

1. When translating English plural forms into Chinese, restore to singular
2. Foreign abbreviations can be represented with half-angle dots
3. Change English ellipsis to Chinese ellipsis
4. When English vocabulary appears for the first time, provide Chinese annotation in parentheses
5. Capitalize the first letter of each word for proper nouns, no need to capitalize non-proper nouns

Proper Noun Usage

• Use correct capitalization (such as GitHub)
• Do not use unidiomatic abbreviations (such as using JavaScript instead of Js)

4. Punctuation Guidelines

Basic Principles

1. Use full-angle symbols for Chinese sentences
2. Use English/half-angle punctuation when the entire sentence is in English
3. Periods, question marks, exclamation marks, commas, etc. should not appear at the beginning of a line
4. Periods should not appear at the end of titles, but marks can

Common Punctuation

• Period: Use full-angle period (。) at the end of Chinese sentences
• Comma: Indicate general pauses within sentences, avoid "comma to the end"
• Enumeration comma: Use full-angle enumeration comma (、) for parallel words within sentences
• Semicolon: Indicate pauses between parallel clauses in complex sentences
• Quotation marks: Use full-angle double quotation marks (" "), with single quotation marks (' ') for the inner layer
• Parentheses: Use full-angle round brackets (（）), without spaces before and after
• Colon: Use full-angle colon (：) for explanations, use half-angle colon (😃 for time
• Ellipsis: Use Chinese ellipsis (⋯⋯), occupying the space of two Chinese characters
• Exclamation mark: Avoid using as much as possible, do not use multiple consecutively
• Dash: Occupies the space of two Chinese characters, used for further explanation
• Hyphen: Use straight hyphen (-) for noun compounds, use wave hyphen (～) for numerical ranges

5. Numerical Guidelines

Basic Rules

1. Arabic numerals should all be in half-angle form
2. Add thousands separator (half-angle comma) for numbers above thousands
3. Currency symbols should be written before numbers, or currency names in Chinese should be written after numbers
4. Numerical ranges should be connected with a tilde (～) or em dash (—)

Degree of Change Expression

• Increase: Use "increased by", "increased to"
• Decrease: Use "decreased by", "decreased to"
• Do not use expressions like "decreased by N times" or "reduced by N times"

6. Spacing Guidelines

Basic Rules

1. Add spaces between links
2. Add spaces before and after bold, italic, highlighted text
3. Do not leave spaces at the end of each line
4. Do not have excessive blank lines
5. Leave one blank line at the end of the file
6. Leave one blank line before and after titles

7. Documentation System

Filename Guidelines

1. Filenames should not contain spaces
2. It is recommended to use only lowercase letters
3. Use half-angle hyphens (-) to separate multiple words