juzhiyuan commented on a change in pull request #974:
URL: https://github.com/apache/apisix-website/pull/974#discussion_r836146718
##########
File path: website/docs/general/documentation-guide.md
##########
@@ -0,0 +1,129 @@
+---
+id: documentation-guide
Review comment:
```suggestion
id: documentation-style-guide
```
##########
File path: website/docs/general/committer-guide.md
##########
@@ -9,31 +9,11 @@ keywords:
description: This article covers some guidelines for Apache APISIX committers.
It walks through the type of contributions and the contributor ladder and how
contributors can become committers and then PMC members.
---
-This article walks through the guidelines for Apache APISIX contributors.
+This document walks through how Apache APISIX contributors are structured.
-See [Contributor Guide](/docs/general/contributor-guide/) to learn more about
the contributing process.
+See [Contributing flow](/docs/general/contributor-guide/) to learn more about
the contributing process.
-## What Can I Contribute?
-
-Any and all forms of contributions are welcome! For example you can,
-
-- Fix issues tagged "[good first
issue](/docs/general/contributor-guide/#good-first-issues)" or "[help
wanted](https://github.com/apache/apisix/issues?q=is%3Aopen+label%3A%22help+wanted%22+sort%3Aupdated-desc)".
-
-- Join the discussions on the [mailing list](/docs/general/subscribe-guide/).
-
-- Answer questions in [issues](https://github.com/apache/apisix/issues) and
[discussions](https://github.com/apache/apisix/discussions).
-
-- Review open [pull
requests](https://github.com/apache/apisix/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc).
-
-- Improve the website.
-
-- Improve documentation or write a blog post.
-
-- Any other form of code or non-code contribution.
-
-If you would like to contribute, let us know by sending an email to
[email protected]!
-
-## How to become an APISIX committer?
+## How do I become an APISIX committer?
Review comment:
Please use `Apache APISIX`
##########
File path: website/docs/general/documentation-guide.md
##########
@@ -0,0 +1,129 @@
+---
+id: documentation-guide
+title: Documentation style guide
+keywords:
+ - API gateway
+ - APISIX
+ - Apache APISIX
+ - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+This document is a style guide for Apache APISIX documentation. This document
is intended for contributors to APISIX's documentation and should be followed
to ensure consistency.
+
+To learn more about contributing, see [Contributing
flow](contributor-guide.md).
+
+## Tone, content and audience
+
+- Aim for a voice and tone that's conversational, friendly, and respectful
without being frivolous. Learn more on [Voice and
tone](https://developers.google.com/style/tone).
+- Write for accessibility. See [General do's and
don'ts](https://developers.google.com/style/accessibility#general-dos-and-donts)
to learn more.
+- Identify the intended audience and write for them. Find the common ground
for you and your target audience.
+
+## Language
+
+- Use second person while writing unless it isn't appropriate.
+- Use active voice while writing.
+- Use standard American spellings.
+- Always place [conditional clauses before
instructions](https://developers.google.com/style/clause-order).
+- Use the following spellings for project specific entities:
+ - Use Apache APISIX instead of APISIX when referencing the project in
introductions and when referencing to the project community.
+ - Use APISIX instead when referencing to the project inside documentation.
+ - APISIX specific component names like Plugin and Route are always
capitalized.
+ - Use correct acronyms when necessary. Use the expanded word in first usage
and proceed to use the acronym in the rest of the references. For example:
+
+ | ✅ | ❌ |
+ | ---------------- | ---------------- |
+ | URL | url |
+ | API | api |
+ | APISIX Dashboard | Apisix dashboard |
+ | gRPC | GRPC/grpc |
+
+## Formatting, punctuation and organization
+
+- Use sentence case for all headings and subheadings.
+- Use advanced markdown features and admonitions provided by Docusaurus when
necessary:
+ - Use [tabs](https://docusaurus.io/docs/next/markdown-features/tabs) and
[synced
tabs](https://docusaurus.io/docs/next/markdown-features/tabs#syncing-tab-choices)
when you have to show multiple paths based on a user's configuration or
environment.
+ - Use [code
blocks](https://docusaurus.io/docs/next/markdown-features/code-blocks) to
display code. Add the file being modified as the title of the codeblock (for
example, `coonf/config.yaml`). Use line highlighting to focus the attention of
the use while explaining code.
+ - Use
[admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions) to
highlight important information. Use them as suggested below:
+ - Note: for general information you want to stand out.
+ - Tip: to give users bonus tips that build on top of the rest of the
content. Can be ignored generally.
+ - Important: to give extra emphasis to general information.
+ - Warning: to highlight possibilities of loss of configuration or data.
+ - Danger: user should be very careful about what is mentioned in the
block. Use only in cases of maximum severity.
+- Use tables to convey appropriate information easily. See [how they are used
in
FAQ](/docs/apisix/FAQ#what-is-the-difference-between-plugin-metadata-and-plugin-configs-in-apache-apisix).
+- Use relative paths within markdown files `../xxx/xxx` instead of absolute
paths.
+
+### Directory structure
+
+The docs are organized as shown below. To create a new page, create a new file
in the latest folder of the language you are writing the doc in.
+
+```text
+/docs
+├── assets
+│ ├── images
+│ │ ├── xxxxx.png
+│ └── other
+│ └── xxxxx.xxx
+├── en
+│ └── latest
+│ ├── doc1.md
+│ ├── folder
+│ │ └── doc2.md
+│ │ └── folder2
+│ │ └── doc3.md
+│ └── config.json
+├── es
+│ └── latest
+│ └── ...
+└── zh
+ └── latest
+ └── ...
+```
+
+### Configuration file
+
+The configuration file is located in `/docs/<locale>/latest/config.json` where
locale represents the locale code (language). Refer to [Locale
Codes](https://www.science.co.il/language/Locale-codes.php) for more info. Note
that locale is always all lowercase.
+
+You can learn more about the sidebar from the [Docusaurus
docs](https://v2.docusaurus.io/docs/next/sidebar).
+
+```json
Review comment:
```suggestion
```jsonc
```
##########
File path: website/docs/general/documentation-guide.md
##########
@@ -0,0 +1,129 @@
+---
+id: documentation-guide
+title: Documentation style guide
+keywords:
+ - API gateway
+ - APISIX
+ - Apache APISIX
+ - project documentations
+description: Style guide for Apache APISIX documentation.
+---
+
+This document is a style guide for Apache APISIX documentation. This document
is intended for contributors to APISIX's documentation and should be followed
to ensure consistency.
+
+To learn more about contributing, see [Contributing
flow](contributor-guide.md).
+
+## Tone, content and audience
+
+- Aim for a voice and tone that's conversational, friendly, and respectful
without being frivolous. Learn more on [Voice and
tone](https://developers.google.com/style/tone).
+- Write for accessibility. See [General do's and
don'ts](https://developers.google.com/style/accessibility#general-dos-and-donts)
to learn more.
+- Identify the intended audience and write for them. Find the common ground
for you and your target audience.
+
+## Language
+
+- Use second person while writing unless it isn't appropriate.
+- Use active voice while writing.
+- Use standard American spellings.
+- Always place [conditional clauses before
instructions](https://developers.google.com/style/clause-order).
+- Use the following spellings for project specific entities:
+ - Use Apache APISIX instead of APISIX when referencing the project in
introductions and when referencing to the project community.
+ - Use APISIX instead when referencing to the project inside documentation.
+ - APISIX specific component names like Plugin and Route are always
capitalized.
+ - Use correct acronyms when necessary. Use the expanded word in first usage
and proceed to use the acronym in the rest of the references. For example:
+
+ | ✅ | ❌ |
Review comment:
Center aligned?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
