[WIP] API docs contrib guide #1592
Conversation
| # Find the workflow for your API docs | ||
|
|
||
| :::{warning} | ||
| This is WIP and apart from the quick reference is just a quick-and-dirty copy/paste from the Confluence doc |
There was a problem hiding this comment.
This is WIP and apart from the quick reference is just a quick-and-dirty copy/paste from the Confluence doc
IMO this isn't a good candidate for externalizing. Or if we do need a page like this, I'd suggest:
- removing any mention of things related to private repos, or "elastic employees only"
- removing the "Publishing process", "Automated?", and "Status" columns in the table since they're not pertinent to external contributors
- referring to the appropriate readmes for all the individual process details, so we are less likely to fall out of sync. For example:
- Elasticsearch: https://github.com/elastic/elasticsearch-specification?tab=readme-ov-file#how-to-generate-the-openapi-representation
- Kibana: https://github.com/elastic/kibana/blob/main/oas_docs/README.md (we can likely make this content better, but should be source of truth IMO)
- Observability intake service: https://github.com/elastic/apm-managed-service/blob/main/docs/spec/openapi/README.md
- Logstash doesn't have a readme but would be simple enough to create one here: https://github.com/elastic/logstash/tree/main/docs/static/spec/openapi
- summarizing the workflow at a high level, since it's essentially the same for all of them: check out the appropriate repo and branch, generate the OpenAPI output (per linked readmes), preview the output and verify that it satisfies the checklist, then open a PR to submit any changes.
There was a problem hiding this comment.
IMO this isn't a good candidate for externalizing.
Yeah this was just a conversation starter for "How do we co-locate a handy overview of the different processes/workflows with the contribution guidance and provide links" which we definitely need
There was a problem hiding this comment.
Or if we do need a page like this, I'd suggest:
I do think we need a page like this, but absolutely in accordance with 3-4
removing the "Publishing process", "Automated?", and "Status" columns in the table since they're not pertinent to external contributors
This isn't just for external contributors though, so we have to allow a little slack for co-locating important info, but yeah shouldn't be talking about super private stuff. But otherwise we have a public doc and a Confluence doc and nobody finds Confluence docs is something I hear all the time. It's also potentially helpful info for any external contributor to know at a glance that they can't contribute to Cloud API docs, for example. Anyways, probably a good debate topic.
removing any mention of things related to private repos, or "elastic employees only"
I don't mind that we mention a couple of private repos in a much more condensed and high-level version of this page, same reasoning as #1592 (comment)
| If you find a bug in the contribution guide itself, please open a PR. | ||
| For small edits that only touch a single page, click the **Edit this page** button. This will take you to the source file in GitHub, where you can make your changes and submit a PR. | ||
|
|
||
| ## Get help |
There was a problem hiding this comment.
Get help
IMO this section should be removed since it's not the type of stuff I'd expect us to externalize.
There was a problem hiding this comment.
Personally I'm OK with co-locating this information because I think realistically Elasticians will be the main consumers of this guidance, and it's helpful to have it all together, but it's a loosely-held position
|
Closing in favor of elastic/docs-content#2229 |
No description provided.