diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 0af35e1c1..f4b640f32 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -10,16 +10,27 @@ Whether you're a technical writer or you've only edited Elastic docs once or twi ## Contribute to the docs [#contribute] -The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. +The version of the docs you want to contribute to determines the tool and syntax you must use to update the docs. The easiest way to find the source file for the page you want to update is to navigate to the page on the web and click **Edit this page**. This will take you to the source file in the correct repo. For more detailed instructions, see [Contribute on the web](on-the-web.md). -### Contribute to Elastic Stack version 8.x docs and earlier +If you need to update documentation for both 8.x and 9.x, you will have to work in two systems. See [What if I need to update both 8.x and 9.x docs?](on-the-web.md#what-if-i-need-to-update-both-8.x-and-9.x-docs) for the processes on updating docs across different versions. -To contribute to earlier versions of the Elastic Stack, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses AsciiDoc as it's authoring format. +### Contribute to version `8.18`, `ECE 3.8`, and `ECK 2.0` docs and earlier -* For **simple bugfixes and enhancements** --> [Contribute on the web](on-the-web.md) -* For **complex or multi-page updates** --> See the [legacy documentation build guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) +To contribute to earlier versions of the documentation, you must work with our [legacy documentation build system](https://github.com/elastic/docs). This system uses the [AsciiDoc](https://asciidoc.org) markup language. -### Contribute to Elastic Stack version 9.0 docs and later +* For **simple bug fixes and enhancements**, refer to [Contribute on the web](on-the-web.md) +* For **complex or multi-page updates**, refer to our [legacy Building documentation guide](https://github.com/elastic/docs?tab=readme-ov-file#building-documentation) + +### Contribute to version `9.0+`, `ECE 4.0+`, and `ECK 3.0+` docs and later + +To contribute to `9.0+`, `ECE 4.0+`, and `ECK 3.0+` content, you need to work with our new documentation system. This system uses custom [Markdown syntax](../syntax/index.md). +The source files for this content are hosted in one of three places: + +1. **Reference/settings content** is generally stored in markdown files in the relevant product repo. For example, the Elasticsearch configuration reference is stored in the [elastic/elasticsearch](https://github.com/elastic/elasticsearch/tree/main/docs) repo. This enables contributors to make updates that touch code and low-level docs in the same PR. +2. **Narrative/conceptual and overview content** lives in [elastic/docs-content](https://github.com/elastic/docs-content). For example, the [ES|QL overview](https://www.elastic.co/docs/explore-analyze/query-filter/languages/esql) lives in the **Explore & Analyze** section of the narrative docs. But the reference documentation lives in the Elasticsearch reference section of the docs: [ES|QL reference](https://docs-v3-preview.elastic.dev/elastic/elasticsearch/tree/main/reference/query-languages/esql) +3. **API reference docs** live in the different OpenAPI spec repositories. This is where you need to update API docs published in the new API docs system. + +When you are ready to edit the content: * For **simple bugfixes and enhancements** --> [contribute on the web](on-the-web.md) * For **complex or multi-page updates** --> [Contribute locally](locally.md) @@ -37,3 +48,4 @@ To contribute to earlier versions of the Elastic Stack, you must work with our [ ## Work on docs-builder That sounds great! See [development](../development/index.md) to learn how to contribute to our documentation build system. +