iSharkFly-Docs
/
opensearch-docs-cn
mirror of https://github.com/iSharkFly-Docs/opensearch-docs-cn
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update style guide (#2939) 

* Update style guide

Signed-off-by: natebower <102320899+natebower@users.noreply.github.com>

* Updates API Style Guide Template

Signed-off-by: natebower <102320899+natebower@users.noreply.github.com>

---------

Signed-off-by: natebower <102320899+natebower@users.noreply.github.com>
This commit is contained in:
Nathan Bower 2023-02-16 15:00:47 -05:00 committed by GitHub
parent 7675466931
commit 7b0a67f30a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 10 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
STYLE_API_TEMPLATE.md
View File

@ -33,8 +33,8 @@ Depending on where the documentation appears within a section or subsection, hea
1. Path parameters (heading level 3)
1. Query parameters (heading level 3)
1. Request fields (heading level 3)
1. Sample request (heading level 4)
1. Sample response (heading level 4)
1. Example request (heading level 4)
1. Example response (heading level 4)
1. Response fields (heading level 3)
## API name
@ -112,7 +112,7 @@ Include a table with these columns:
Field | Data type | Description
:--- | :--- | :---
#### Sample request
#### Example request
Provide a sentence that describes what is shown in the example, followed by a cut-and-paste-ready API request in JSON format. Make sure that you test the request yourself in the Dashboards Dev Tools console to make sure it works. See the examples below.
@ -136,7 +136,7 @@ POST _reindex
}
```
#### Sample response
#### Example response
Include a JSON example response to show what the API returns. See the examples below.

8
STYLE_GUIDE.md
View File

@ -1,4 +1,4 @@
# OpenSearch Project style guidelines
# OpenSearch Project Style Guidelines
Welcome to the content style guide for the OpenSearch Project. This guide covers the style standards to be observed when creating OpenSearch content and will evolve as we implement best practices and lessons learned in order to best serve the community.
@ -154,7 +154,7 @@ The following table lists acronyms that you don't need to spell out.
### Formatting and organization
- Use a colon to introduce example blocks (for example, sample code and scripts) and most lists. Do not use a colon to introduce tables or images.
- Use a colon to introduce example blocks (for example, code and scripts) and most lists. Do not use a colon to introduce tables or images.
- Use bold text for all UI elements, including pages, panes, and dialog boxes. In all cases, emphasize what the user must do as opposed to talking about the UI element itself.
@ -221,6 +221,8 @@ A procedure is a series of numbered steps that a user follows to complete a spec
- Parallel language constructions
- Consistent formatting
Use *example*, not *sample*, to introduce example blocks (for example, code, scripts, and API requests and responses).
Replace pointer-specific language with device-agnostic language to accommodate readers with disabilities and users of various input methods and devices, including the pointer, keyboard, and touch screens.
For example, instead of the term *click*, which is pointer-specific, use *choose*, which is more generic and device-agnostic. However, when the generic language makes it difficult to understand the instructions (for example, in the case of opening a context menu), you can include pointer-specific hints. Use your judgment. If you have a question, ask your editor.
@ -300,6 +302,8 @@ Here are two styles you can use for topic titles:
* Field types
* Security analytics
Use *example*, not *sample*, in headings that introduce example blocks (for example, code, scripts, and API requests and responses).
## UI text
Consistent, succinct, and clear text is a critical component of a good UI. We help our users complete their tasks by providing simple instructions that follow a logical flow.