Writing Specification

[miss85246]

Ok, everyone, I think you can take the initiative to read this issue, which shows that you already know what we are going to do. let's beginning!

Writing Specification

In the process of contributing guide documents, we should have a consistent writing standard to help vuepress display
better and translators translate more easily. so now we draft this document for every contributor and translator.

the document has 2 part:

Overall

Most of our documents are written by the markdown. The current rules are as follows:

1. Heading levels should only increment by one level at a time

When using multiple heading levels, nested headings should increase by only one level at a time:

# Heading1

## Heading2

### Heading3

2. First heading should be a top-level heading

please let document Heading start at H1.

# Heading1

3. Clear separation of paragraphs

• Between the title and body
• Between paragraphs and paragraphs
• Between code blocks and code blocks
• vuepress grammar block and markdown grammar block

In the scenario described above, we should keep the paragraphs clear and keep an empty line between them.

# Heading

this is some content...

::-1

the vuepress block should have an empty line with markdown content.

-1::

4. Every sentence should end with appropriate punctuation marks.

Ensure that every sentence ends with punctuation marks such as period, ellipsis and question mark.

Do you often encounter problems during use sanic ?

yes, but I can find the solution from sanic froums.

you can add it again, again, again...

5. please don't end with empty line in code block.

in python file, because of PEP8, we often end with an empty line. In markdown file, it's will let code block display
more ugly. vuepress will automatically add empty line when rendering. Please don't manually add empty line in the end of
code block.

in python file, because of PEP8, we often end with an empty line.

6. Leave blank before and after grammar blocks in sentences.

√: you can use `request` object and ...

×: you can use`request`object and...

If there are multiple consecutive syntax blocks, only one space is left at the beginning and end of the consecutive
syntax blocks

√: the method `get`, `post` are allowed.

×: the method `get` ,  `post` are allowed.

For the use of numbers in a sentence, we also try to leave a blank space.

√: I have 20 apps.

×: I have20 apps.

7. Try to use Arabic numerals.

It is inevitable to use numbers in our usual writing process. Please use Arabic numerals as much as possible.

√: It has about 32 bytes.

×: It has about thirty-two bytes.

8. Use PEP8 in code block for Python.

PEP8 is a standard Python writing standard. When you write Python in code block, please apply PEP8.

9. Try to avoid using italics

In vuepress, italics can't bring great display effect, because its font is too thin, please use bold instead of italics.

√: build faster, run **faster**

×: build faster, run *faster*

10. Emphasize keywords, not the whole sentence

In some sentences, if we emphasize a whole sentence, we can't find the key point. We should try to emphasize the
keywords instead of the whole sentence.

√: Quite much configuration is **required** to allow fast transparent proxying...

×: **Quite much configuration is required to allow fast transparent proxying...**

Custom

For some specific languages, They have a special writing standard. such as Chinese, Japanese, Korean. Because of the
particularity of language, they need special writing format.

Translators can negotiate with each other to reach a consensus. Just keep the style consistent on the basis of the above.

[miss85246]

This is all my thoughts for the time being. If you have any good suggestions, please let me know and we can discuss them further.

[ZinkLu]

A good guideline for a official documents.

I wonder if there are tools that can help us format or check contents as yapf or pylint in python. It's could be more and more difficult to follow with increments of translated language and contributors.

[miss85246]

I recommend using Markdown All in one plugin in vscode or useing Markdown plugin in Jetbrains eidtors. they are support markdownlint.

[smlbiobot]

I’d suggest having a punctuation style for lists. e.g. I personally prefer always using . periods to end each item, some prefer leaving it. They can be either, but they should be consistent.

Your issue actually is inconsistent about this:

1. Heading levels should only increment by one level at a time
2. First heading should be a top-level heading
3. Clear separation of paragraphs
4. Every sentence should end with appropriate punctuation marks.
5. please don't end with empty line in code block.
…

So it probably should be:

1. Heading levels should only increment by one level at a time.
2. First heading should be a top-level heading.
3. Clear separation of paragraphs.
4. Every sentence should end with appropriate punctuation marks.
5. Please don't end with empty line in code block.
…

This is generally my preference:

• Always use a . (period / full stop) for sentences.
• You can use no punctuations if it’s a quick list of one-word items.
• Always start sentences / items in Title Case.

[miss85246]

@smlbiobot You're right. I didn't notice this. I'll correct it later and add it to the Writing Specification.

[smlbiobot]

Here are some of the more possibly mundane thoughts but that I think would be an improvement.

---

Do you often encounter problems during use sanic ?

Do you often encounter problems during use Sanic?

• Remove space between sanic and ?
• Determine if Sanic should always be spelled lower case or title case when referred in sentences. I personally think that Sanic as a name should always be title case, but when referenced in code and as a package, then it should be used in lowercase but for that use ideally surround with sanic inline code-block.

---

yes, but I can find the solution from sanic froums.

• typo for forums

---

you can add it again, again, again...

• Prefer real ellipsis … over three dots ... (these are typographic decisions. It usually doesn’t bother developers. But if I’ve found docs that are written with this much care in them, I tend to note that and appreciate the project more!

---

This is same for when the docs use real curly quotes (another typographic thing):

Instead of:

"That's a 'magic' shoe."

Write:

“That’s a ‘magic’ shoe.”

This example is from https://typographyforlawyers.com/straight-and-curly-quotes.html — a great article if you have no idea what I’m talking about!

[miss85246]

@smlbiobot Sorry, I'm busy moving these days.
It‘s overturn my idea 😮.
In my impression, English has always been must used the straight single quote (') and the straight double quote (").
I didn't know that opening quote and closing quote are also used in English until today 😲.
please don't laugh at my ignorance， I really don't know 😢 .
thanks for your suggestion， It’s let me learn a lot.
I will sort it out and continue to accept your opinions. 😃