Skip to content

[WIP] API docs contrib guide #1592

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from

Conversation

leemthompo
Copy link
Contributor

No description provided.

@leemthompo leemthompo self-assigned this Jul 21, 2025
@leemthompo leemthompo added the documentation Improvements or additions to documentation label Jul 21, 2025
# 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
Copy link
Contributor

@lcawl lcawl Jul 21, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

  1. removing any mention of things related to private repos, or "elastic employees only"
  2. removing the "Publishing process", "Automated?", and "Status" columns in the table since they're not pertinent to external contributors
  3. referring to the appropriate readmes for all the individual process details, so we are less likely to fall out of sync. For example:
  4. 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.

Copy link
Contributor Author

@leemthompo leemthompo Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

@leemthompo leemthompo Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Get help

IMO this section should be removed since it's not the type of stuff I'd expect us to externalize.

Copy link
Contributor Author

@leemthompo leemthompo Jul 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@leemthompo
Copy link
Contributor Author

Closing in favor of elastic/docs-content#2229

@leemthompo leemthompo closed this Jul 23, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants