docs(skills): update writing-user-docs layout to ADR 0023 revision

[dhshah13]

The writing-user-docs skill's Directory Layout still shows the original two-directory split (admin/ and user/) from ADR 0023. The ADR's Revision (2026-05) split admin/ into getting-started/ and infrastructure/, with user/ and dev/ unchanged; docs/guides/README.md indexes all four trees.

The stale layout causes skill-compliance reviews to flag correctly-placed guides as structure violations (e.g. Qodo on #6429 flagged docs/guides/infrastructure/distributed-tracing.md and docs/guides/dev/tracing.md).

Updates the layout snippet, the directory checklist line, and the audience wording to match the revised structure, citing the revision. Docs only.

[github-actions]

E2E tests did not run

E2E tests run automatically for org/repo members and collaborators on pull requests.

For other contributors, a maintainer must add the ok-to-test label after the latest push.

See E2E testing guide for details.

[qodo-code-review]

PR Summary by Qodo

Align writing-user-docs skill layout with ADR 0023 revision (2026-05)

📝 Documentation 🕐 10-20 Minutes

AI Description

• Update writing-user-docs audience definitions to match ADR 0023’s revised guide structure.
• Refresh the docs/guides/ directory layout snippet to the four-directory split.
• Fix checklist/mistake guidance to prevent false “wrong directory” compliance flags.

Diagram

graph TD
  A["skills/writing-user-docs/SKILL.md"] --> B["ADR 0023 (Rev 2026-05)"] --> C["docs/guides/README.md"] --> D["getting-started/"] --> E["infrastructure/"] --> F["user/"] --> G["dev/"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Remove the directory tree snippet; link to ADR/README only

• ➕ Eliminates duplicated structure that can drift and cause future compliance false-positives
• ➕ Keeps the skill focused on rules rather than mirroring canonical docs
• ➖ Less immediately scannable for authors who want a quick “where does this go?” answer
• ➖ Requires an extra click to see the structure

2. Auto-sync layout snippet from docs/guides/README.md (generated include)

• ➕ Keeps skill layout always consistent with the index
• ➕ Reduces manual upkeep across multiple docs
• ➖ Adds tooling/build complexity for a small documentation benefit
• ➖ Harder to edit locally without understanding the generation pipeline

Recommendation: Current approach is good: keep the quick layout snippet in the skill, but explicitly cite ADR 0023’s Revision (2026-05) and point to docs/guides/README.md as the canonical index to reduce future ambiguity. If drift becomes recurring, consider dropping the snippet entirely in favor of links.

Files changed (1) +23 / -12

Documentation (1) +23 / -12

SKILL.mdUpdate guide audience and directory layout to ADR 0023 revision +23/-12

Update guide audience and directory layout to ADR 0023 revision

• Rewords the overview to reflect the revised audience split (org maintainers, platform operators, developers, contributors). Updates the directory layout example to the four-tree structure and adds an explicit note citing ADR 0023’s Revision (2026-05) with a link to the guides index. Adjusts checklist and common-mistake wording to avoid outdated admin/user-only guidance.

skills/writing-user-docs/SKILL.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Dev guides omitted scope ✓ Resolved 🐞 Bug ≡ Correctness

Description

The skill frontmatter description only mentions getting-started/infrastructure/user guides, but
this same skill document (and ADR 0023 revision) includes a dev/ tree for contributor guides. This
inconsistency can cause authors/reviewers to incorrectly skip this skill when updating
docs/guides/dev/* guides.

Code

skills/writing-user-docs/SKILL.md[R5-7]

+  docs/guides/. Use when creating getting-started or infrastructure guides
+  (install, configure, operate) or user guides (workflows, interactions,
+  interventions) for fullsend.

Relevance

●● Moderate

Similar description-completeness nitpicks (renumber-adr desc) were rejected once; no strong recent
precedent either way.

PR-#3610

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The changed frontmatter description mentions only getting-started/infrastructure/user, while the
same file’s layout section includes dev/ and the official guides index documents a Development
section under docs/guides/dev/—showing the omission is inconsistent with the repo’s documented
structure.

skills/writing-user-docs/SKILL.md[2-7]
skills/writing-user-docs/SKILL.md[20-32]
docs/guides/README.md[49-58]
docs/ADRs/0023-user-documentation-structure.md[96-99]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The skill frontmatter `description` omits the `dev/` (contributors) audience even though the skill’s own “Overview” and “Directory Layout” explicitly include `dev/`. This creates conflicting guidance about when to apply the skill.

## Issue Context
ADR 0023 Revision (2026-05) and `docs/guides/README.md` both document a `dev/` directory as part of the `docs/guides/` structure.

## Fix Focus Areas
- skills/writing-user-docs/SKILL.md[2-7]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 58 rules

✅ Skills: writing-user-docs, writing-adrs

Tip of the day

💡 Did you know, you can copy the agent prompt from any finding and feed it to your IDE agent

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗