[GitHub] [apisix] navendu-pottekkat opened a new issue #6672: docs: create a style guide to ensure consistency in documentation

[GitBox <gi...@apache.org>]

navendu-pottekkat opened a new issue #6672:
URL: https://github.com/apache/apisix/issues/6672


   ### Current State
   
   The current docs are written by multiple individual contributors often having different styles.
   
   There isn't any enforced style for documentation that the contributors can refer to.
   
   ### Desired State
   
   Create a style guide that defines a style to follow while contributing to documentation.
   
   All additions and modifications to the documentation is expected to follow the guidelines mentioned in this style guide.
   
   We could follow/fork a standard guide like the one for [Google developer documentation](https://developers.google.com/style/highlights) and add guides specific to our project.
   
   Some of the areas where I think we need to decide the style are mentioned below:
   
   1. Whether or not to capitalise component names like Route/route, Plugin/plugin while internally referencing them.
   2. Whether/where to use sample values/variables in code snippets or provide a placeholder value.
   3. How to highlight significant points? When should we use [Admonitions](https://docusaurus.io/docs/next/markdown-features/admonitions)?
   4. What other Docusaurus features should we use and when? (Ex Code Highlighting)
   5. Is it Apache APISIX or just APISIX when referring in docs?
   6. How to link internal documents? Relative paths? Full path from root? How to link files in multiple repos?
   7. Title case or sentence case for headings
   
   Please add any other areas where style should be consistent. There is another open issue to be worked in parallel for the Chinese documentation: https://github.com/apache/apisix/issues/6651


-- 
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: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix] juzhiyuan commented on issue #6672: Proposal: create a style guide to ensure consistency in documentation

[GitBox <gi...@apache.org>]

juzhiyuan commented on issue #6672:
URL: https://github.com/apache/apisix/issues/6672#issuecomment-1073531312


   Link to https://github.com/apache/apisix/issues/6461


-- 
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: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix] juzhiyuan edited a comment on issue #6672: Proposal: create a style guide to ensure consistency in documentation

[GitBox <gi...@apache.org>]

juzhiyuan edited a comment on issue #6672:
URL: https://github.com/apache/apisix/issues/6672#issuecomment-1073531312


   Link to https://github.com/apache/apisix/issues/6461, also cc @hf400159 


-- 
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: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

[GitHub] [apisix] yzeng25 closed issue #6672: Proposal: create a style guide to ensure consistency in documentation

[GitBox <gi...@apache.org>]

yzeng25 closed issue #6672:
URL: https://github.com/apache/apisix/issues/6672


   


-- 
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: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org