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.

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

• For simple bugfixes and enhancements --> contribute on the web
• For complex or multi-page updates --> Contribute locally

Starting with Elastic Stack version 9.0, ECE 4.0, and ECK 3.0, a new set of docs is no longer published for every minor release. Instead, each page stays valid over time and incorporates version-specific changes directly within the content using a cumulative approach.

Cumulative documentation means that one page can cover multiple product versions, deployment types, and release stages. Instead of creating separate pages for each release, we update the same page with version-specific details.

This helps readers understand which parts of the content apply to their own ecosystem and product versions, without needing to switch between different versions of a page.

Following this approach, information for supported versions must not be removed unless it was never accurate. Instead, refactor the content to improve clarity or to include details for other products, deployment types, or versions.

In order to achieve this, the markdown source files integrate a tagging system meant to identify:

• Which Elastic products and deployment models the content applies to.
• When a feature goes into a new state as compared to the established base version.

This tagging system is mandatory for all of the public-facing documentation.

Use the applies_to tag to indicate which versions, deployment types, or release stages each part of the content is relevant to.

You must always use the applies_to tag at the page level. Optionally, you can also use it at the section or inline level if certain parts of the content apply only to specific versions, deployment types, or release stages.

• 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.