elastic / elastic/docs-builder

[cumulative docs] Identify opportunities for automation and linting

Open
#1,744 2 comments 0 reactions 0 assignees View on GitHub
ai-triaged ai:eng-question ai:writer-question cumulative_docs Project:Quality stale
Dominant language
C#
Stars
24
Forks
44
Avg merge
1d 7h
Merged PRs (30d)
146

Description

## Context

In #1614 we added a bunch of new guidance for writing cumulative documentation including `applies_to` usage and placement. These guidelines are quite complicated. I think there are opportunities to build some automation and/or linting rules that could help us provide guidance in context at build time and reduce the amount of content docs contributors need to read and internalize.

## Opportunities for automation / assertions

- [x] Sort `applies_to` badges. This is already in progress:
* Within a single key in `applies_to`, always order versions from newest to oldest ([docs-builder#1726](https://github.com/elastic/docs-builder/pull/1726))
* Across all keys in `applies_to`, always use the same order for keys ([docs-builder](https://github.com/elastic/docs-builder/pull/1727)#1727)
- [ ] Sort tabs with `applies_to`. This is dependent on #1436.
- [ ] Render `applies_to` badge at the beginning of a list item regardless of where it is added in the source.
* Note: I'm not sure if we actually want to do this or if we should just lint for badges that are not at the beginning of a list item and prompt the contributor to move the badge via a hint or warning.
- [ ] Render `applies_to` badge at the beginning of a paragraph regardless of where it is added in the source
* Note: I'm not sure if we actually want to do this or if we should just lint for badges that are not at the beginning of a paragraph and prompt the contributor to move the badge via a hint or warning.
- [ ] Throw a warning on section applies_to in h1 (title)
* Use `applies_to` in the frontmatter instead
- [ ] Throw a warning on inline applies_to in h1 (title)
* Use `applies_to` in the frontmatter instead
- [x] Throw a warning on inline applies_to in any h2+ (https://github.com/elastic/docs-builder/pull/1777)
* Use section `applies_to` instead

_I'll keep adding more as needed._

cc @theletterf (since we talked about this a bit)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.