elastic / elastic/beats

Reduce duplication in documentation

Open
#50,821 8 comments 4 reactions 0 assignees View on GitHub
docs Team:Elastic-Agent-Data-Plane
Dominant language
Go
Stars
12.7k
Forks
5k
Avg merge
2d 15m
Merged PRs (30d)
385

Description

Since we migrated to markdown docs in 9.0, each Beat has their own set of documentation files, even for the shared components like processors. This generates a lot of duplication and toil when any shared component needs to have their documentation updated.

Here is an example for the add docker metadata processor:
```
% find . -name 'add-docker-metadata.md'
./docs/reference/auditbeat/add-docker-metadata.md
./docs/reference/heartbeat/add-docker-metadata.md
./docs/reference/filebeat/add-docker-metadata.md
./docs/reference/winlogbeat/add-docker-metadata.md
./docs/reference/packetbeat/add-docker-metadata.md
./docs/reference/metricbeat/add-docker-metadata.md
```

Some of those files are also pretty much duplicated in the Fleet documentation that resides at [docs-content](https://github.com/elastic/docs-content), ex: https://github.com/elastic/docs-content/blob/main/reference/fleet/add_docker_metadata-processor.md

Ideally we would have a single source of truth [like in 8.19](https://github.com/elastic/beats/blob/8.19/libbeat/processors/add_docker_metadata/docs/add_docker_metadata.asciidoc) that gets rendered for each Beat during the docs build process.

This issue is about discussing the possibility of having some automation that can render the duplicated docs from a single source of truth. The processors are a good candidate to start with, but there are many sections in the Beats documentation that are the same for all Beats.

Contributor guide

Open the contributing guide

Research direction

Compare the duplicated processor pages under docs/reference/*/add-docker-metadata.md with the historical source at libbeat/processors/add_docker_metadata/docs/add_docker_metadata.asciidoc and the Fleet copy in docs-content. Start by mapping which sections are shared and how the docs build currently renders them. Done means a concrete automation design or implementation path that supports a single source of truth across Beats documentation.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
build-system, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.