id: ‘documentation_style_guide’ title: ‘Documentation Style Guide’ sidebar_position: 4

1 The English edition specification

1.1 Manual Line Break

When you're writing documents, please break lines intentionally around the approximate character limit (120 chars), which makes it easier for review and developers to read.

1.2 3-C rules

  • Clarity:

Ensure that your writing is clear and simple. Generally speaking, use active voice and unambiguous pronouns. Write short sentences, insisting on one viewpoint per sentence. Before using new terminology, it is necessary to define it and maintain the target audience.

  • Simplicity:

Knowing how much to say is important when writing any document. If you provide too much detail, the page will become dull and difficult to read, and it will be rarely used.

  • Consistency:

Ensure that you consistently use the same wording throughout the entire page and across multiple pages.

1.3 Reduce Markers

Reduce the number of markers (such as code blocks, bold text) unless absolutely necessary, as the rendered version becomes very difficult to read.

1.4 Correct Item Reference

  • Positive：

    Apache HBase, ClickHouse.

  • Negative：

    Apache Hbase, Clickhouse.

1.5 Integrity and Availability

  • English documentation should have corresponding Chinese documentation pages.
  • Internal links referenced in the English documentation should be functional, and corresponding pages in other languages should be accessible.
  • External links referenced in the English documentation should be functional.
  • If there are incomplete resources, it's preferable to declare the supplementary time or plan for missing resources, and add a simple explanation if necessary.

1.6 Using inclusive expression

Click here for more details.

1.7 Space

  • Between English words and numbers
  • Between English words and units
  • Between English words and links

1.8 Punctuation Marks

  • Use half-width English punctuation marks when using the English input method.

1.9 Capitalization of The First Letter

The first letter of the first word in a sentence should be capitalized unless there are special circumstances.

  • Positive：

    ‘nameMap’(Assuming the attribute name is ‘nameMap’) is an attribute of class Demo.

    Jige is a pretty basketball player.

  • Negative：

    ‘NameMap’ is an attribute of class Demo.

    Jige is a pretty basketball player.

For better

If you are interested in ensuring the standardized writing quality of the document, please let's reference this link to do better.

References