Skip to content

Commit 639e08d

Browse files
authored
Add API docs contribution guidance under extend/contribute (#2229)
- Adds minimal `contribute` section - Related issue: #1773 - Links to docs-builder contribution docs (not in scope to migrate all that in this PR) - Adds API docs contrib guidance
1 parent e2e93f7 commit 639e08d

File tree

13 files changed

+1441
-1
lines changed

13 files changed

+1441
-1
lines changed
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
navigation_title: Checklist
3+
---
4+
5+
# API docs checklist
6+
7+
Use this checklist to verify the quality, completeness, and consistency of your API docs contributions.
8+
9+
## Structure, organization, and metadata
10+
- Include required [OpenAPI document info](./organize-annotate.md#add-open-api-document-info)
11+
- Include [OpenAPI specification version](./organize-annotate.md#add-openapi-specification-version)
12+
- Define unique [operation identifiers](./organize-annotate.md#add-operation-identifiers) using camelCase
13+
- Use consistent [tags](./organize-annotate.md#group-apis-with-tags) to group related operations
14+
- Document [API lifecycle status](./organize-annotate.md#specify-api-lifecycle-status) (availability, stability, version information)
15+
- Mark deprecated APIs and properties with appropriate notices
16+
- Document [required permissions](./organize-annotate.md#document-required-permissions) for each operation
17+
18+
## Content quality and completeness
19+
20+
- Write clear [summaries](./guidelines.md#write-summaries) (between 5-45 characters)
21+
- Write detailed [descriptions](./guidelines.md#write-descriptions) for operations, parameters, properties, tags etc.
22+
- Document all [parameters](./guidelines.md#document-parameters) and explain how changing defaults affects behavior
23+
- Provide descriptions for non-obvious [enum values](./guidelines.md#document-enum-values)
24+
- Specify [default values](./guidelines.md#set-default-values) for optional parameters
25+
- Include realistic [examples](./guidelines.md#add-examples) with helpful descriptions
26+
- Add [links](./guidelines.md#add-links) to related operations and documentation
27+
28+
## Quality assurance
29+
30+
- Preview your changes locally before submitting (see [Contribute locally: Elasticsearch quickstart](./quickstart.md))
31+
- [Lint your API docs](guidelines.md#lint-your-api-docs) to identify and fix issues
32+
- Check all links to ensure they work correctly
33+
- Ensure examples are realistic and error-free

0 commit comments

Comments
 (0)