From f9c5f8331be22cd6f3b05aebccf0b44e66afa933 Mon Sep 17 00:00:00 2001 From: Oz Date: Sat, 1 Aug 2026 17:14:14 +0000 Subject: [PATCH] docs(skills): improve drafting skills from signal log patterns 2026-08-01 Add additive guidance for section order, troubleshooting placement, callout sparsity, Settings-path orientation, and screenshot discipline based on human review patterns from agent-authored docs PRs. Co-Authored-By: Oz --- .agents/skills/draft_docs/SKILL.md | 11 ++++++++++- .agents/templates/feature-doc.md | 19 +++++++++++++++---- .agents/templates/procedural.md | 12 ++++++++---- 3 files changed, 33 insertions(+), 9 deletions(-) diff --git a/.agents/skills/draft_docs/SKILL.md b/.agents/skills/draft_docs/SKILL.md index 41fccc5a..43523a5c 100644 --- a/.agents/skills/draft_docs/SKILL.md +++ b/.agents/skills/draft_docs/SKILL.md @@ -93,6 +93,11 @@ These rules are frequently violated by agents. Apply them carefully during draft - **Tables or parallel bullets for comparison and reference data** — When you present two or more parallel items (key types, plan tiers, environments) or structured reference data (API endpoints, parameters), use a Markdown table or tightly parallel bullets instead of one dense paragraph. ✅ a table with one row per API endpoint, or parallel `**Personal API keys**` / `**Agent API keys**` bullet groups ❌ a single paragraph mixing both key types and their billing rules - **Bold for UI elements** — Use `**Save**` not `` `Save` `` after action verbs like "click" - **Bold per-segment for Settings paths** — Use `**Settings** > **AI** > **Knowledge**` not `` `Settings > AI > Knowledge` `` +- **Orient the reader before every Settings path, CLI command, or URL** — On first reference in the page, name the app or tool. ✅ `In the Warp app, go to **Settings** > **AI** > **Knowledge**.` ❌ `Go to **Settings** > **AI** > **Knowledge**.` +- **Section order follows reader chronology** — Prerequisites and requirements before setup, setup before usage, usage before advanced options. ✅ `## Prerequisites` → `## Set up the integration` → `## Start a run` ❌ setup steps before the reader knows what they need +- **Keep error messages out of the main flow** — Do not weave full error strings through conceptual or procedural sections. Put them in a dedicated `## Troubleshooting` section near the end (symptom → cause → fix). ✅ one Troubleshooting section with the exact error as a bold lead-in ❌ repeating the same error callout after every step +- **Use callouts sparingly** — Prefer body prose. At most one or two callouts per page unless the content type template requires more. ✅ a single `:::note` for a non-obvious prerequisite ❌ a `:::note` / `:::tip` after every subsection +- **Screenshots only when the UI is hard to describe** — Prefer prose for straightforward clicks. If you include an image, use descriptive alt text (not "screenshot") and place it after the concept it illustrates. Do not invent or request screenshots of internal-only, flagged, or unfinished UI. ### 7. Draft the doc Create the documentation using the appropriate template from `.agents/templates/`. Follow the structure for the identified content type and all rules in `AGENTS.md`. Each template includes visible bracketed instructions explaining what to put in each section. @@ -117,16 +122,20 @@ Skip steps 1–3 in local/interactive sessions. Before presenting the draft, verify against the quality checklist in `AGENTS.md`: - [ ] Frontmatter includes clear description written as a standalone summary - [ ] Content follows the structure for its content type +- [ ] Section order follows reader chronology (requirements → setup → usage → advanced → troubleshooting) +- [ ] Error messages and failure modes live in Troubleshooting, not woven through the main flow +- [ ] Callouts are sparse (usually 0–2 per page) and not used as a substitute for body prose - [ ] Terminology matches the glossary (`.agents/references/terminology.md`) - [ ] Headers use sentence case (with proper feature name capitalization) - [ ] Lists use bold term + dash + explanation format - [ ] Cross-references to related features are included +- [ ] First Settings path, CLI, or URL on the page names the app or tool - [ ] Instructions include expected outcomes - [ ] Procedures are scannable: dense sections are split into numbered steps, short bullets, or concise subsections - [ ] UI surfaces and product terms use canonical names from `.agents/references/terminology.md` - [ ] Product names with a corresponding entry in `src/data/vars.ts` use the variable syntax (`{VARS.KEY}` in prose, `{{TOKEN}}` in frontmatter) — not hardcoded strings - [ ] If AEO-driven, the draft follows the AEO brief, uses source vocabulary naturally, and avoids duplicative or junk-drawer coverage -- [ ] Images have descriptive alt text +- [ ] Images have descriptive alt text and are used only when the UI is hard to describe in prose ### 10. Update navigation and redirects If this is a new page, remind the user to: diff --git a/.agents/templates/feature-doc.md b/.agents/templates/feature-doc.md index 4f3d24ca..07ba89a3 100644 --- a/.agents/templates/feature-doc.md +++ b/.agents/templates/feature-doc.md @@ -34,15 +34,18 @@ Focus on what each capability means for the user.] Explain "what" and "why" before "how." Define new terms when they first appear. IMPORTANT: Do NOT include step-by-step procedures in this section. -Keep the conceptual and procedural sections clearly separated.] +Keep the conceptual and procedural sections clearly separated. +Do NOT embed full error messages here — put failures in Troubleshooting at the end.] ## [Usage/configuration section — sentence case. Rename to match the feature, e.g., "Creating environments", "Configuring integrations"] [PROCEDURAL section: step-by-step instructions. +Order sections for the reader: Prerequisites → setup/config → day-to-day usage → advanced options. Apply all procedural rules from AGENTS.md: - Motivate steps before giving instructions - Include expected outcomes after key steps -- Group related actions when they share the same UI context] +- Group related actions when they share the same UI context +- Name the app before the first Settings path or CLI command on this page] ### Prerequisites @@ -58,12 +61,20 @@ Include: what the thing is, where to get it, link to full reference.] ## [Additional sections as needed — sentence case. e.g., "Managing X", "Advanced usage"] [Repeat the conceptual or procedural pattern as appropriate. -Keep sections clearly delineated by type.] +Keep sections clearly delineated by type. +Avoid stacking multiple callouts; prefer short prose unless a caveat is easy to miss.] + +## Troubleshooting + +[Optional but recommended when the feature has common failures, permission errors, or exact platform error strings. +Place this section near the end of the page, before Related pages. +Format each item as: bold symptom or exact error message, then cause, then fix. +Do not scatter the same error callouts through earlier sections.] ## Related pages [Cross-references to related features, next steps, deeper references. -Use descriptive link text.] +Use descriptive link text. Include at least one related feature or next-step link on new feature pages.] * [Related feature](path/to/page.md) * [Deeper guide](path/to/page.md) diff --git a/.agents/templates/procedural.md b/.agents/templates/procedural.md index d7428196..a5d360e6 100644 --- a/.agents/templates/procedural.md +++ b/.agents/templates/procedural.md @@ -17,9 +17,11 @@ See AGENTS.md → Content variables for the full variable list and usage rules.] ## Prerequisites -[Only if needed. Bulleted list with inline context for each prerequisite. +[Only if needed. Place prerequisites before any setup or usage steps. +Bulleted list with inline context for each prerequisite. Each item should include: what it is (1 short clause), where to get or create it, and a link to the full reference. +Name the app before Settings paths and CLI commands. Example: * **A Warp API key** - Authenticate API requests with a key from **Settings** > **Cloud platform** > **Oz Cloud API Keys** in the Warp app. See [API Keys](path) for details.] @@ -27,7 +29,7 @@ Example: ## [Primary task name — sentence case. e.g., "Creating API keys"] [Brief motivation: why the reader would do this (1 sentence). -Then numbered steps.] +Then numbered steps. Keep failure details for the Troubleshooting section below.] 1. Step description. 2. Step description. @@ -46,8 +48,10 @@ descriptive content as appropriate.] ## Troubleshooting [Optional but recommended. Common issues the reader might encounter -while following these steps. -Format: symptom/error as bold text, then cause and fix.] +while following these steps. Keep this section near the end of the page. +Put exact error messages here instead of weaving them through the steps above. +Format: symptom or exact error string as bold text, then cause and fix. +Use at most one callout in this section unless multiple unrelated failures need separation.] ## Best practices