Gocloudcoder replies to books to receive learning materials, including Linux, Golang, Java, JS, operating systems, computer networks, programming experience, algorithms and data structures, etc.

This article is referenced in document-style-Guide

Document system

structure

  • Introduction to the

  • Quick learning

  • Introductory article

    • Environment to prepare
    • The installation
    • Set up the

  • Advanced article

  • API

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

Issues for attention

(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, secondary heading A contains only one tertiary heading, and tertiary heading A can be ignored entirely.

A

### A

## Secondary title
Copy the code

(3) Carefully use four-level headings, avoid appearing as far as possible, and keep the hierarchy simple.

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

Example: Use a list of items in the following article structure.

###

* A
* B
* 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 write markdown documents in a formal way. Correct: This article describes how to write markdown documents in a formal way.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.

True: On December 17, 2020, I was writing my 68th tech blog. True: On December 17, 2020, I was writing my 68th tech blog.Copy the code

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

Wrong: He uses Ubuntu. Correct: He uses Ubuntu.Copy the code

The sentence

(1) Avoid long sentences, use simple sentences and compound sentences.

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

(2) Use positive sentences to express, not negative sentences.

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

(3) Avoid using double negative sentences.

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 active voice.

Error: False so the software is not installed. Correct: If the software has not been installed.Copy the code

(2) Use a formal language style (see personal style, but official technical documentation should be formal, personal blog can be humorous).

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

English to deal with

(1) English ellipsis (…) Should be changed to Chinese ellipsis (……) .

英文 : five minutes later... [Adjust to Chinese input method, then press Shift + 6]Copy the code

(2) English and Chinese titles.

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

(3) When English words appear for the first time, give Chinese marks in brackets. When it appears again, use English abbreviation directly.

IOC (International Olympic Committee) Use "IOC" directly after.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. The following statements serve the core sentence.
  • A paragraph should be no longer than 7 lines. The best paragraph length should be no more than 4 lines.
  • Separate paragraphs with a blank line.

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 WikiQuote] (https://github.com/ruanyf/document-style-guide/blob/master/docs/paragraph.md)
Copy 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