Add API docs contribution guidance under extend/contribute #2229
Conversation
|
Note I renamed folder and the actions bot is now generating 404 links 🔍 Preview links for changed docs |
|
Yay, splendid that you're spearheading this, @leemthompo ! |
| - **TypeScript API definitions** contain JSDoc comments with descriptions, annotations, and type information | ||
| - **JSON spec files** define endpoint URLs, HTTP methods, and parameters for each API | ||
| - **Example YAML files** provide realistic request/response demonstrations | ||
| - **OpenAPI overlays** allow customization of the generated OpenAPI documents for specific consumers |
There was a problem hiding this comment.
Not sure if we should use so much bold everywhere, tbh.
There was a problem hiding this comment.
Fair, can revisit :)
| --- | ||
| navigation_title: Find your team's workflow | ||
| --- | ||
| # Find the workflow for your API docs |
There was a problem hiding this comment.
What is a workflow in this context? We don't define it.
There was a problem hiding this comment.
I hate this page title TBH and "workflow" is very placeholdery 🛟
Workflow = Each team has its own process for producing their OpenAPI files in their respective repositories
There was a problem hiding this comment.
Should external contributors be concerned about team structure? Shouldn't we rather talk of "products" or "areas" or "features", or simply how to find your way to the right API docs source?
There was a problem hiding this comment.
s/team/product 👍
Need help on the title of this page tho
How can we boil How do the different products do their API docs down into a suitably compact formulation?
There was a problem hiding this comment.
I have a candidate
|
|
||
| # Contribute to Elastic documentation | ||
|
|
||
| Find the relevant pages for contributing to the official Elastic documentation. |
There was a problem hiding this comment.
What defines Legacy and Current? How does one know?
There was a problem hiding this comment.
What defines Legacy and Current? How does one know?
Basically by reading the information in the table 😄
I'm seeking to delegate to the docs-builder docs for the granularities in this first iteration, until those docs get moved here and we revisit
- 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
|
|
||
| :::: | ||
|
|
||
| ## Document path parameters |
There was a problem hiding this comment.
will it be the same for headers or query parameters? good to state those as well.
|
|
||
| Path parameters are variables in URL paths that users must provide to access specific resources. Proper documentation helps users understand what values are expected and how to construct valid requests. | ||
|
|
||
| Here are some principles for documenting path parameters: |
There was a problem hiding this comment.
Would it be good to include links where users can find the params if they don't know where to find them?
| Here are some principles for effective examples: | ||
|
|
||
| - **Use realistic data:** Provide examples that reflect actual use cases rather than placeholder values | ||
| - **Write clear summaries:** Introduce the example with a very brief summary that explains its purpose (reused as dropdown label in the docs) |
There was a problem hiding this comment.
maybe recommend some word limit on summaries to ensure devs don't describe it too much
| - **Write clear descriptions:** Explain what the example accomplishes in more detail and why it's useful | ||
| - **Include edge cases:** Show how to handle optional parameters, error conditions, and different response types | ||
| - **Point out key details:** Highlight important aspects users might miss | ||
| - **Show variations:** Demonstrate alternative approaches or related concepts |
There was a problem hiding this comment.
how many do we expect? good to state clearly that they can provide happy path and any specific business cases that must be known to devs/users
There was a problem hiding this comment.
Not sure if it's helpful to give a specific number, but the wording here could be improved
| - **Point out key details:** Highlight important aspects users might miss | ||
| - **Show variations:** Demonstrate alternative approaches or related concepts | ||
| - **Provide realistic response bodies:** Each response body should have a realistic example. It must not contain any sensitive or confidential data | ||
| - **Include success responses:** Include at least one example for each success response (HTTP 200) |
There was a problem hiding this comment.
Don't we need other response codes and the respective samples to be documented?
There was a problem hiding this comment.
This is about examples specifically not documenting response codes, so I think the focus is on 200s
Sorry misread, not sure if the guidance is provide examples of every possible response code, I was just pulling from existing guidance here :)
| - Mark deprecated APIs and properties with appropriate notices | ||
| - Document [required permissions](./organize-annotate.md#document-required-permissions) for each operation | ||
|
|
||
| ## Content quality and completeness |
There was a problem hiding this comment.
is there any tool we can recommend for devs to use? Like Grammarly? so they can formulate better texts in the .yaml or code.
There was a problem hiding this comment.
I don't think so, but the linter helps per the QA list
| navigation_title: Contribute locally (Elasticsearch) | ||
| --- | ||
|
|
||
| # Contribute locally: Elasticsearch quickstart |
There was a problem hiding this comment.
This looks like specifically for elasticsearch-specification repo. do we plan to add similar quickstarts later for other APIs since they come in with different workflows?
There was a problem hiding this comment.
Agreed, I would contribute this to elasticsearch-specification directly. We have a lot of this already mentioned in README.md and CONTRIBUTING.md.
There was a problem hiding this comment.
We have a lot of this already mentioned in README.md and CONTRIBUTING.md.
Yes but those pages aren't really end-to-end about docs, and they are not well organized today. I at least wanted to have this E2E workflow documented in one place. We can discuss how we handle overlap going forward.
This looks like specifically for elasticsearch-specification repo. do we plan to add similar quickstarts later for other APIs since they come in with different workflows?
We needed a concrete workflow for this guidance to not be super high-level and impractical. Because the Elasticsearch APIs are our largest set, and the entire workflow isn't laid out in a step-by-step fashion anywhere, we decided that we should have this, somewhere. We have a lot of work to fix the gaps in the Elasticsearch API docs. The easier we make it for contributors to help out, the faster that will happen.
do we plan to add similar quickstarts later for other APIs since they come in with different workflows?
This is very MVP, so there isn't a super long term plan right now and yeah ultimately, maybe this page goes away and we just link to the repos in workflows.md
|
|
||
| Once you're satisfied with your docs changes: | ||
| 1. Create a pull request from a branch on your local clone | ||
| 2. The CI will validate your OpenAPI specs |
There was a problem hiding this comment.
after all approvals are done & the devs merge this PR, do you also want to talk about backporting in case that fails? or is that left to us?
There was a problem hiding this comment.
we can mention backporting gotchas too for sure
There was a problem hiding this comment.
Can we rename "JSON spec files" into "rest-api-spec"? Or add both.
I'm not sure I understand why there are two paths to Clients. I would have
- Removed "generated Client Libraries"
- Removed "converted OpenAPI for Clients, Dev Tools Console, etc."
- Kept "used by "Clients, Dev Tools Console, etc."
There was a problem hiding this comment.
Can we rename "JSON spec files" into "rest-api-spec"? Or add both.
Will do
So I came to believe that the Schema JSON is used to generated the Client Libraries
And I thought we had two sets of Open API files: 1 used for clients, 1 for API reference
I'll ping you with alternatives in Slack because hard to iterate on mermaid diagrams in a PR :)
| navigation_title: Contribute locally (Elasticsearch) | ||
| --- | ||
|
|
||
| # Contribute locally: Elasticsearch quickstart |
There was a problem hiding this comment.
Agreed, I would contribute this to elasticsearch-specification directly. We have a lot of this already mentioned in README.md and CONTRIBUTING.md.
contributesectionReviewers
URL preview
Note
Previews: #2229 (comment) (ignore comment bot links)