Reduce duplication in documentation
- 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
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