Skip to content

Commit ae67103

Browse files
committed
Updates to checklist and worflows pages per Fab's review
- Reordered sections: moved "Structure, organization, and metadata" before "Content quality and completeness" - Removed all checkboxes and converted to plain bullet points - Added reference to quickstart guide for previewing - Removed validation checklist item about OpenAPI document structure - Changed navigation title from "Find your team's workflow" to "API docs by product" - Updated heading from "Find the workflow for your API docs" to "How each Elastic product manages API docs" - Shifted language from "team" to "product" terminology in descriptions
1 parent a9f2279 commit ae67103

File tree

2 files changed

+23
-25
lines changed

2 files changed

+23
-25
lines changed

extend/contribute/api-docs/checklist.md

Lines changed: 20 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -6,30 +6,28 @@ navigation_title: Checklist
66

77
Use this checklist to verify the quality, completeness, and consistency of your API docs contributions.
88

9-
## Content quality and completeness
10-
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
1117

12-
- ☑️ Write clear [summaries](./guidelines.md#write-summaries) (30 characters max, start with a verb)
13-
- ☑️ Write detailed [descriptions](./guidelines.md#write-descriptions) for operations, parameters, properties, tags etc.
14-
- ☑️ Document all [path parameters](./guidelines.md#document-path-parameters) with constraints and formats
15-
- ☑️ Provide descriptions for non-obvious [enum values](./guidelines.md#document-enum-values)
16-
- ☑️ Specify [default values](./guidelines.md#set-default-values) for optional parameters
17-
- ☑️ Include realistic [examples](./guidelines.md#add-examples) with helpful descriptions
18-
- ☑️ Add [links](./guidelines.md#add-links) to related operations and documentation
18+
## Content quality and completeness
1919

20-
## Structure, organization, and metadata
21-
- ☑️ Include required [OpenAPI document info](./organize-annotate.md#add-open-api-document-info)
22-
- ☑️ Include [OpenAPI specification version](./organize-annotate.md#add-openapi-specification-version)
23-
- ☑️ Define unique [operation identifiers](./organize-annotate.md#add-operation-identifiers) using camelCase
24-
- ☑️ Use consistent [tags](./organize-annotate.md#group-apis-with-tags) to group related operations
25-
- ☑️ Document [API lifecycle status](./organize-annotate.md#specify-api-lifecycle-status) (availability, stability, version information)
26-
- ☑️ Mark deprecated APIs and properties with appropriate notices
27-
- ☑️ Document [required permissions](./organize-annotate.md#document-required-permissions) for each operation
20+
- Write clear [summaries](./guidelines.md#write-summaries) (30 characters max, start with a verb)
21+
- Write detailed [descriptions](./guidelines.md#write-descriptions) for operations, parameters, properties, tags etc.
22+
- Document all [path parameters](./guidelines.md#document-path-parameters) with constraints and formats
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
2827

2928
## Quality assurance
3029

31-
- ☑️ Preview your changes locally before submitting
32-
- ☑️ [Lint your API docs](guidelines.md#lint-your-api-docs) to identify and fix issues
33-
- ☑️ Check all links to ensure they work correctly
34-
- ☑️ Ensure examples are realistic and error-free
35-
- ☑️ Validate that your OpenAPI document is well-formed
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

extend/contribute/api-docs/workflows.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
2-
navigation_title: Find your team's workflow
2+
navigation_title: API docs by product
33
---
4-
# Find the workflow for your API docs
4+
# How each Elastic product manages API docs
55

6-
Each team has its own process for producing their OpenAPI files in their respective repositories. This page provides a quick reference to help you navigate to the right resources.
6+
Each product has a specific process for producing OpenAPI files in the respective repositories. This page provides a quick reference to help you navigate to the right resources.
77

88
:::{important}
99
Some of the content on this page is relevant to Elastic employees only and therefore some links are to private repos.

0 commit comments

Comments
 (0)