Skip to content

Technical Document Writing Guidelines

As we all know, having a consistent style and adhering to grammar rules can make articles more readable and reduce communication costs.

Article Structure

When writing technical articles, you can refer to the following structure:

# Article Title

A sentence or two introducing the content of the article.

## Demo

Please provide a brief introduction to the usage of the demo and demonstrate its effects.

## Principle

Please gradually introduce the principles.

## Conclusion

Provide a simple summary.

## References and Acknowledgements

- [Reference 1](Link to Reference 1)
- [Reference 2](Link to Reference 2)

Formatting Guidelines

Paragraphs

  • When using Markdown syntax, the first line does not need to be indented.
  • There should be a blank line between paragraphs to differentiate them.

Scenarios Requiring Spaces

  • Between Chinese and English, and between Chinese and numbers:

    Incorrect: Qt生成器是一个针对C++的跨平台IDE
    Correct: Qt 生成器是一个针对 C++ 的跨平台 IDE

  • Between numbers and units (except between numbers and percentage sign):

    Incorrect: 其频率为 72MHz，占空比为 50 %。
    Correct: 其频率为 72 MHz，占空比为 50%。

  • Between regular text and special characters (links, bold, italics, etc.):

    This font uses bold style. Please click here to subscribe.

  • After English half-width punctuation marks:

    Hello, world

  • Between Chinese and em dash:

    Markdown - a efficient way of writing

Text Styles

  1. When mixing Chinese and English, use Chinese full-width punctuation marks by default.
  2. When mixing Chinese and English, if there is a complete English sentence, use English half-width punctuation marks within that sentence.
  3. Inline links are generally bolded to improve readability.
  4. Use accurate proper nouns:

    Incorrect: 使用 github 登录
    Correct: 使用 GitHub 登录

  5. Use straight quotation marks for Chinese, instead of regular quotation marks:

    Incorrect: 华广机器人队，也称为“野狼队”
    Correct: 华广机器人队，也称为「野狼队」

  6. Avoid repeating punctuation marks for emphasis.

Writing Style

  • If it is not necessary, do not add unnecessary entities.
  • To improve readability, try to avoid using long sentences and break them into multiple simple sentences if possible.
  • Arguments should be supported by evidence, avoid making claims without examples.

References and Acknowledgements

Original: https://wiki-power.com/
This post is protected by CC BY-NC-SA 4.0 agreement, should be reproduced with attribution.

This post is translated using ChatGPT, please feedback if any omissions.