Document Style Guide

The Document Style Guide provides editorial guidelines for writing clear and consistent documentation, especially for team members in Monitoring and Alerting team. The intent of these guidelines is to help maintain a consistent voice in Monitoring and Alerting articles.

punctuation ¶

No space between words and punctuation, add space after punctuation - [Mandatory] ¶

You can configure most Jekyll settings, such as your site's theme and plugins, by editing your _config.yml file

You can configure most Jekyll settings ,such as your site's theme and plugins,by editing your _config.yml file

Don't repeat your punctuation - [Mandatory] ¶

What are you talking about?

What are you talking about???

Right case / words for proper noun - [Recommend] ¶

We use GitHub as our code repository.

We use github as our code repository.

He knows a lot of frontend knowledges such as JavaScript, HTML5, AngularJS, etc.

He knows a lot of FE knowledges such as js, h5, angular...

In a series of three or more items, use a comma before the final and or or - [Recommend] ¶

I dedicate this book to my parents, Ayn Rand, and God.

I dedicate this book to my parents, Ayn Rand and God.

Don't use slashes to separate alternatives - [Recommend] ¶

Call this method five or six times.

Call this method 5/6 times.

Paragraph ¶

Don't add too much contents in a single paragraph - [Mandatory] ¶

The length of a paragraph cannot exceed seven lines, recommend to make it less than five lines.

Add a new line between two paragraphs - [Recommend] ¶

If not use new line to separate, some markdown platform can not distinct two paragraphs.

Only have one topic for each paragraph - [Recommend] ¶

Header ¶

There are 5 levels of title, from Header 1 (<H1>) to Header 5 ( <H5>).

Don't cross header level - [Mandatory] ¶

Header 3 should not following Header 1 directly.

# H1
### H3

Avoid using single header on one level - [Mandatory] ¶

Don't add only one header AA under header A.

## H2 A
### H3 AA
## H2 B

Don't repeat up level header's name - [Recommend] ¶

## Overview
### Overview

Be cautious of using header 4, never use header 5 - [Reference] ¶

Keep hierarchy as simple as possible, and prevent making chapters too complex. Sometimes could use list instead of header.

### H3
- A
- B
- C

### H3
#### H4 A
#### H4 B
#### H4 C

Number ¶

Use commas and decimal points in accordance with standard American number-formatting - [Recommend] ¶

in numbers four or more digits long, use commas to set off groups of three digits, counting leftward from the decimal point, in the standard American style.

For long decimal numbers, do not use any digit-group separators to the right of the decimal point.

The limit is 1,532,784 bytes per day.
$0.031611/vCPU hour

The limit is 1532784 bytes per day.
$0.031 611/vCPU hour

Use hyphen for ranges of numbers - [Reference] ¶

Use a hyphen with no space on either side of it. Do not use an en dash (–) or em dash (—).

See more about hyphen.

2012-2016

Reference ¶

Cisco Technical Content Style Guide

google developer documentation style guide

Apple Style Guide

Microsoft Writing Style Guide