Add API docs contribution guidance under extend/contribute #2229

leemthompo · 2025-07-23T10:33:26Z

Adds minimal contribute section
- Related issue: [Website] Consolidating public docs contribution guidelines #1773
- Links to docs-builder contribution docs (not in scope to migrate all that in this PR)
Adds API docs contrib guidance

Reviewers

Page titles could be improved
What's missing that we need in this first iteration?

URL preview

Note

Previews: #2229 (comment) (ignore comment bot links)

leemthompo · 2025-07-23T11:38:32Z

Note

I renamed folder and the actions bot is now generating 404 links

🔍 Preview links for changed docs

extend/contribute/api-docs/overview.md

extend/contribute/api-docs/workflows.md

extend/contribute/api-docs/overview.md

Co-authored-by: Lisa Cawley <[email protected]>

theletterf · 2025-07-24T08:57:52Z

Yay, splendid that you're spearheading this, @leemthompo !

github-actions · 2025-07-25T03:00:51Z

🔍 Preview links for changed docs

theletterf

First review pass!

extend/contribute/api-docs/checklist.md

theletterf · 2025-07-25T10:04:55Z

extend/contribute/api-docs/overview.md

+- **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


Not sure if we should use so much bold everywhere, tbh.

Fair, can revisit :)

here's a vote to keep the bold 👍 for scannability

extend/contribute/api-docs/quickstart.md

theletterf · 2025-07-25T10:05:38Z

extend/contribute/api-docs/workflows.md

+---
+navigation_title: Find your team's workflow
+---
+# Find the workflow for your API docs


What is a workflow in this context? We don't define it.

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

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?

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?

I have a candidate

theletterf · 2025-07-25T10:06:12Z

extend/contribute/index.md

+
+# Contribute to Elastic documentation
+
+Find the relevant pages for contributing to the official Elastic documentation.


What defines Legacy and Current? How does one know?

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

ketkee-aryamane

A good first start to this process. :))
I left some comments and questions, if you think it's nitpicking, feel free to ignore.

extend/contribute/api-docs/guidelines.md

ketkee-aryamane · 2025-07-25T12:10:39Z

extend/contribute/api-docs/guidelines.md

+- **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


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

Not sure if it's helpful to give a specific number, but the wording here could be improved

extend/contribute/api-docs/guidelines.md

extend/contribute/api-docs/checklist.md

ketkee-aryamane · 2025-07-25T12:25:11Z

extend/contribute/api-docs/quickstart.md

+navigation_title: Contribute locally (Elasticsearch)
+---
+
+# Contribute locally: Elasticsearch quickstart


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?

Agreed, I would contribute this to elasticsearch-specification directly. We have a lot of this already mentioned in README.md and CONTRIBUTING.md.

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

extend/contribute/api-docs/quickstart.md

pquentin

Thanks! I think I see the point of having docs specifically for the docs aspect of the specification. Should we link to the Elasticsearch specification docs, such as the modeling guide?

extend/contribute/api-docs/images/es-api-docs-pipeline.png

pquentin · 2025-07-25T14:12:23Z

extend/contribute/api-docs/quickstart.md

+navigation_title: Contribute locally (Elasticsearch)
+---
+
+# Contribute locally: Elasticsearch quickstart


Agreed, I would contribute this to elasticsearch-specification directly. We have a lot of this already mentioned in README.md and CONTRIBUTING.md.

summary of diff: • renamed section from "document path parameters" to "document parameters" • broadened scope to all parameter types, not just path params • added note about explaining effect of changing defaults • adjusted summary character count guideline (5-45 chars vs 30 max) • simplified parameter documentation principles • reorganized examples section for path parameters • added clarification about default values impact • removed elastic-employee-specific help content • simplified api ownership reference table • updated pipeline diagram with clearer naming • added step about backporting changes in quickstart • removed private repository references • renamed workflows page title • various minor text improvements

Add API docs contribution guidance under extend/contribute

b838633

leemthompo mentioned this pull request Jul 23, 2025

[WIP] API docs contrib guide elastic/docs-builder#1592

Closed

leemthompo added 9 commits July 23, 2025 12:40

typos, links

37ab7b4

fix up me anchor

e9bb158

🔗

c6a4e7f

simplify dir name

b28203c

what

6b7b7bb

link from contribution overview page

4737397

Improve nav title

dcf1aca

typo

420f95c

typomg

0925813

elastic deleted a comment from github-actions bot Jul 23, 2025

tweak toc descriptions

234d002

elastic deleted a comment from github-actions bot Jul 23, 2025

lcawl reviewed Jul 24, 2025

View reviewed changes

extend/contribute/api-docs/overview.md Show resolved Hide resolved

lcawl reviewed Jul 24, 2025

View reviewed changes

extend/contribute/api-docs/workflows.md Show resolved Hide resolved

lcawl reviewed Jul 24, 2025

View reviewed changes

extend/contribute/api-docs/workflows.md Outdated Show resolved Hide resolved

leemthompo commented Jul 24, 2025

View reviewed changes

extend/contribute/api-docs/overview.md Outdated Show resolved Hide resolved

tweaks

37e2d01

Co-authored-by: Lisa Cawley <[email protected]>

leemthompo requested review from georgewallace and szabosteve July 24, 2025 06:57

leemthompo marked this pull request as ready for review July 24, 2025 06:57

leemthompo requested a review from a team as a code owner July 24, 2025 06:57

elastic deleted a comment from github-actions bot Jul 24, 2025

leemthompo self-assigned this Jul 24, 2025

leemthompo mentioned this pull request Jul 24, 2025

[Website] Consolidating public docs contribution guidelines #1773

Open

georgewallace approved these changes Jul 25, 2025

View reviewed changes

Merge branch 'main' into leemthompo/api-docs-contrib

a9f2279

theletterf reviewed Jul 25, 2025

View reviewed changes

pquentin mentioned this pull request Jul 25, 2025

Fix "Contribute and extend" link elastic/docs-builder#1612

Merged

ketkee-aryamane reviewed Jul 25, 2025

View reviewed changes

pquentin reviewed Jul 25, 2025

View reviewed changes

leemthompo mentioned this pull request Jul 29, 2025

ESQL: Update text formats documentation elastic/elasticsearch-specification#5054

Merged

leemthompo and others added 5 commits July 30, 2025 15:30

Merge branch 'main' into leemthompo/api-docs-contrib

4d25041

Fixing links: Chapter 90000000

1f15927

Update diagram

47aee56

Merge branch 'main' into leemthompo/api-docs-contrib

a201cbc

leemthompo enabled auto-merge (squash) July 30, 2025 15:20

leemthompo merged commit 639e08d into main Jul 30, 2025
8 of 9 checks passed

leemthompo deleted the leemthompo/api-docs-contrib branch July 30, 2025 15:22


		# Contribute to Elastic documentation

		Find the relevant pages for contributing to the official Elastic documentation.

Add API docs contribution guidance under extend/contribute #2229

Add API docs contribution guidance under extend/contribute #2229

Conversation

leemthompo commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewers

URL preview

Uh oh!

leemthompo commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

theletterf commented Jul 24, 2025

Uh oh!

github-actions bot commented Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

theletterf left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ketkee-aryamane left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo Jul 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leemthompo Jul 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pquentin left a comment

Choose a reason for hiding this comment

Uh oh!

leemthompo commented Jul 23, 2025 •

edited

Loading

leemthompo commented Jul 23, 2025 •

edited

Loading

github-actions bot commented Jul 25, 2025 •

edited

Loading

leemthompo Jul 29, 2025 •

edited

Loading

leemthompo Jul 25, 2025 •

edited

Loading