Elastic Docs contribution guide

Welcome, contributor!

Whether you're a technical writer or you've only edited Elastic docs once or twice, you're a valued contributor. Every word matters!

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.

To contribute to earlier versions of the Elastic Stack, you must work with our legacy documentation build system. This system uses AsciiDoc as it's authoring format.

• For simple bugfixes and enhancements --> Contribute on the web
• For complex or multi-page updates --> See the legacy documentation build guide

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? for the processes on updating docs across different versions.

For all 9.0+ content, it lives in one of three spots:

1. Reference/settings content lives in the new Markdown files in the code repo as it did pre 9.0. This enables folks to make updates that touch code + low-level docs in the same PR.
2. Narrative/conceptual and overview content lives in elastic/docs-content. As an example the ES|QL overview lives in the Explore & Analyze section of the narrative docs. But the reference documentation lives in the reference section of the docs ES|QL reference
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
• For complex or multi-page updates --> Contribute locally

• It's a documentation problem --> Open a docs issue or Fix it myself
• It's a build tool (docs-builder) problem --> Open a bug report

• Make the documentation better --> Open a docs issue
• Make our build tool (docs-builder) better --> Start a docs-builder discussion

That sounds great! See development to learn how to contribute to our documentation build system.

You can use the following sections to help you determine where the content you might want to work on lives.

Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs:

• explore-analyze: Discover, Dashboards, Visualizations, Reporting, Alerting, dev tools...
• deploy-manage: Stack management (Spaces, user management, remote clusters...)
• troubleshooting: troubleshooting pages

• Reference content, anything that is or could be auto-generated: Settings, syntax references, functions lists...
• Release notes
• Developer guide

Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs:

• explore-analyze: query languages, scripting, machine learning (NLP)
• deploy-manage: deploying elastic, production guidance, security, and Management
• manage-data: data store, migration, data lifecycle
• solutions: core search, playground, hybrid search
• troubleshooting: troubleshooting pages

• Reference content (anything that is or could be auto-generated): Settings, syntax references, functions lists…
• Contribution guides and extending elasticsearch (clients, etc)
• Release notes

Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs:

• deploy-manage: deploying cloud
• cloud-account: managing your cloud organization
• troubleshooting: troubleshooting pages

• Reference content (= anything that is or could be auto-generated): Settings, syntax references, functions lists…
• Release notes

Public-facing narrative and conceptual docs have moved. Most can now be found under the following directories in the new docs:

• deploy-manage: deploying cloud, managing your cloud organization
• troubleshooting: troubleshooting pages

• Reference content, anything that is or could be auto-generated): Settings, syntax references, functions lists…
• Release notes

The following section shows a mapping of the different areas in the docs IA to the product areas and topics.