Skip to content

docs: Documentation analysis and improvement #981

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
github-actions wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: Documentation analysis and improvement #981

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/workflows/gh-aw-autodoc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Additional guidance encoded in `additional-instructions` for both audit and fix

- **Secret documentation:** Before proposing (audit) or implementing (fix) any documentation related to secret definitions or usage, the agent must consult [`elastic/observability-github-secrets`](https://github.com/elastic/observability-github-secrets) and its root `README.md` as the Observability org source of truth for secret management. The fix stage must not add guidance that contradicts or extends beyond that source.
- Treat leading `-` (and similar) in **table cells** as potentially intentional (for example icon or status placeholders); avoid “cleaning” them without evidence of a real defect.
- Preserve existing markdown link fragments (`#...`) unless target-heading verification proves a correction is required; when editing links with fragments, validate against the target heading slug first. This includes icon-prefixed headings where the valid slug starts with `-`: the `-` character is a valid replacement for a leading icon in heading text and therefore a valid part of the anchor slug (for example, changing `[Lab 01: Troubleshooting](01-installation-setup.md#-troubleshooting-quick-reference)` to `[Lab 01: Troubleshooting](01-installation-setup.md#troubleshooting-quick-reference)` is invalid when the verified slug is `#-troubleshooting-quick-reference`).
- Preserve existing markdown link fragments (`#...`) unless target-heading verification proves a correction is required; when editing links with fragments, validate against the target heading slug first. This includes icon-prefixed headings where the valid slug starts with `-`: the `-` character is a valid replacement for a leading icon in heading text and therefore a valid part of the anchor slug (for example, changing ``[Lab 01: Troubleshooting](01-installation-setup.md#-troubleshooting-quick-reference)`` to ``[Lab 01: Troubleshooting](01-installation-setup.md#troubleshooting-quick-reference)`` is invalid when the verified slug is `#-troubleshooting-quick-reference`).
- Do not hand-edit **auto-generated** documentation in the fix PR (docs-only); the audit should steer fixes toward generators, templates, or other sources of truth, and the PR body should record any follow-up that is outside this workflow’s scope.
- Preserve or lightly refresh **legacy inline comments** that still document useful context or history; avoid deleting them only for brevity.

Expand Down