docs: improve Chinese copywriting

[kwanhur]

Improved or typo fixed.

Copywriting in docs/zh/latest have different formats:

• some writings have one space before/after English words but some have no.
• some punctuations used in halfwidth form but some in fullwidth. what's differences between fullwidth and halfwidth

Solution

• Add copywriting guidelines, include rules[1]

reference: chinese-copywriting-guidelines

• Add lint tool in code-lint workflow

[1]
Spacing

• Place one space before/after English words
• Place one space before/after numbers
• Place one space between numbers and units
• No additional spaces before/after punctuation in fullwidth form
• text-spacing to the rescue?

Punctuation

• Avoid duplicate punctuation

Fullwidth and halfwidth

• Use punctuation in fullwidth form
• Use numbers in halfwidth form
• Use punctuation in halfwidth form for English sentences

[tzssangglass]

LGTM, let's check with the tool.

[tzssangglass]

would you like to do it?

[tzssangglass]

@juzhiyuan PTAL

[juzhiyuan]

Hi @kwanhur, thanks for your suggestion! I support using a unified writing guideline, after reading https://sparanoid.com/note/chinese-copywriting-guidelines/ it looks good to me 🙌

1. We could use Lint tools to format styles first;
2. Support Lint CI to do formats automatically or just checker;
3. Update (more correctly is rewrite) Chinese Contents according to that guideline.

[kwanhur]

would you like to do it?

Yep, I'll take part in the improving jobs.

[kwanhur]

Lint tool I recommend autocorrect, it's binary supports to lint and fix, would be easily integrated into ci workflow. Autocorrect usage:

autocorrect --help
AutoCorrect 1.5.6
Jason Lee <huacnlee@gmail.com
A linter and formatter for help you improve copywriting, to correct spaces, punctuations between CJK (Chinese, Japanese,
Korean).

USAGE:
    autocorrect [FLAGS] [OPTIONS] <file>...

FLAGS:
        --debug      Print debug message.
        --type       Directly use set file type
        --fix        Automatically fix problems and rewrite file.
    -h, --help       Prints help information
        --lint       Lint and output problems.
    -V, --version    Prints version information

[juzhiyuan]

LGTM, and please note:

We only allow Actions that are official "Made by GitHub" or local to the Apache org on GitHub, to address a potential security vulnerability. This is an incident-related policy change. We are researching the situation, and the policy may evolve based on what we learn.

NEVER use 3rd-party actions directly in your worfklows - use the "submodule" pattern. Example PR [Tobiasz Kędzierski](https://cwiki.apache.org/confluence/display/~tobked)  [opened in SuperSet](https://github.com/apache/superset/pull/12709) showing how this could be done. Also ASF INFRA allow-listed some of the popular Actions out there, including my "cancel workflow" action, but I there is no public list of those available. The nice things about submodules is that they do not bring action code to your repo. They link to commit hashes of the Actions, and that integrates well with the GitHub review process so that committers have better chance to review the changes before they are merged. By using submodules, you are automatically following the GitHub recommendations for [hardening of security for 3rd-party actions](https://docs.github.com/en/actions/learn-github-actions/security-hardening-for-github-actions#using-third-party-actions).

also, check those 3 articles:

1. https://github.blog/changelog/2021-04-22-github-actions-maintainers-must-approve-first-time-contributor-workflow-runs/
2. https://infra.apache.org/github-actions-secrets.html
3. https://cwiki.apache.org/confluence/display/BUILDS/GitHub+Actions+status#GitHubActionsstatus-Thereasonfortheissue

[kwanhur]

Thx for the tips. I think we can treat autocorrect integration as staticcheck in code-lint job.

[pottekkat]

We should probably create a style guide for APISIX. We can start with documentation so that it can remain consistent. For the English docs, we could have something similar to https://developers.google.com/style/highlights where we outline how everything should be and add details specific to the project.

[kwanhur]

We should probably create a style guide for APISIX. We can start with documentation so that it can remain consistent. For the English docs, we could have something similar to https://developers.google.com/style/highlights where we outline how everything should be and add details specific to the project.

LGTM. Docs writers will benefit from the document style guide.