Documentation

Technical documentation patterns, structure, maintenance, and avoiding common documentation failures.

Security Scan

The skill is an instruction-only documentation guide whose content, requirements, and behavior are consistent with its stated purpose.

Purpose & Capability

Name and description match the SKILL.md content: guidance on docs structure, maintenance, and anti-patterns. The skill requests no binaries, env vars, installs, or config paths — all proportional to a writing/documentation helper.

Instruction Scope

SKILL.md contains prescriptive guidance (readme essentials, example policies, maintenance patterns) and does not instruct the agent to read local files, access secrets, call external endpoints, or perform system operations. It mentions tooling (e.g., markdown-link-check) as recommendations but gives no commands or remote endpoints to contact.

Install Mechanism

No install spec and no code files (instruction-only). Nothing is downloaded or written to disk by the skill itself.

Credentials

No environment variables, credentials, or config paths are required or referenced. The guidance does not depend on external secrets or service tokens.

Persistence & Privilege

always is false and model invocation is allowed (platform default). The skill does not request persistent presence or permissions to modify other skills or system settings.

Assessment

This is an instruction-only documentation guide and appears internally consistent and low-risk. You can install it without providing credentials or allowing downloads. Note: the agent platform still allows autonomous invocation by default, but this skill’s content does not request sensitive data or system access. If you plan to combine this skill with other skills or give the agent elevated permissions, review those other skills and permissions separately before enabling autonomous runs.

Structure Hierarchy

• README: what it is, how to install, quick example — 5 minutes to first success
• Getting Started: guided tutorial for beginners — one complete workflow
• Guides: task-oriented ("How to X") — goal-focused, not feature-focused
• Reference: exhaustive API/CLI docs — complete but not for learning
• Troubleshooting: common errors with solutions — search-optimized

README Essentials

1. One-sentence description — what problem it solves
2. Installation — copy-paste command that works
3. Quick start — minimal example that actually runs
4. Link to full docs — don't cram everything in README

Missing any of these = users bounce before trying.

Code Examples

• Every example must be tested — untested examples rot within months
• Show complete runnable code, not fragments — users copy-paste
• Include expected output — confirms they did it right
• Bad: client.query(...) / Good: full script with imports, setup, and output
• Version-pin examples: npm install package@2.1.0 not npm install package

API Documentation

• Every endpoint needs: method, path, parameters, request body, response, error codes
• Show real request/response bodies — not just schemas
• Include authentication in every example — most common missing piece
• Document rate limits and pagination upfront — not buried in footnotes
• Error responses need as much detail as success responses

What Gets Outdated

• Screenshots — UI changes, screenshots don't
• Version numbers — hardcoded versions become wrong
• Links — external sites move, break constantly
• "Current" anything — write timelessly or add review dates
• Feature flags and experimental warnings — often forgotten after GA

Maintenance Patterns

• Docs live next to code — same repo, same PR. Separate repos drift
• CI checks for broken links — markdown-link-check or equivalent
• Runnable examples as tests — if example breaks, build fails
• Review date in docs: "Last verified: 2024-01" — signals freshness
• Delete aggressively — outdated docs worse than no docs

Common Failures

• Documenting implementation, not usage — users don't care how it works internally
• Assuming context — define acronyms, link prerequisites
• Wall of text — use headings, bullets, code blocks liberally
• "See X for more info" without link — friction kills follow-through
• Changelog as documentation — changes ≠ how to use current version

Writing Style

• Imperative mood: "Run the command" not "You can run the command"
• Second person: "you" not "the user"
• Present tense: "This returns X" not "This will return X"
• Short sentences — one idea per sentence
• Active voice: "The function returns X" not "X is returned by the function"

Searchability

• Use words users search for — not internal jargon
• Error messages verbatim in troubleshooting — users paste exact errors
• Multiple ways to describe same thing — alias common variations
• H2/H3 headings are SEO — match user queries
• Avoid clever titles — "Getting Started" beats "Your Journey Begins"

Versioned Documentation

• Major versions need separate docs — v1 users shouldn't see v2 docs
• Migration guides between versions — step-by-step, not just changelog
• Default to latest stable, link to older versions
• Mark deprecated features clearly — don't just remove
• URL structure: /docs/v2/ not query params

README Anti-patterns

• Badge spam — 15 badges before content
• Massive feature lists — save for marketing page
• No installation instructions — assuming everyone knows
• Screenshots without context — what am I looking at?
• License-only README — legal compliance ≠ documentation