Writing Specification about sanic-guide

[miss85246]

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

[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.

[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. 😃