developer-docs

Files (20)

• SKILL.md
• api-endpoint-template.md · assets/
• how-to-template.md · assets/
• quickstart-template.md · assets/
• readme-template.md · assets/
• tutorial-template.md · assets/
• api-dx.md · references/
• code-comments.md · references/
• diataxis.md · references/
• docs-architecture.md · references/
• examples.md · references/
• lifecycle.md · references/
• llm-ready-docs.md · references/
• magic-path.md · references/
• readmes.md · references/
• sdks.md · references/
• stakeholder-docs.md · references/
• standards.md · references/
• style.md · references/
• inventory_docs.py · scripts/

SKILL.md (first lines)

# Developer Docs Authoring and Architecture

## Mission

Create developer documentation that is technically authoritative, easy to navigate, maintainable with the product, and optimized around real developer outcomes.

Treat documentation as part of product design. If an API, SDK, CLI, configuration model, error model, install flow, or workflow is hard to explain cleanly, identify the underlying developer-experience problem rather than writing around it.

Use Diátaxis as the information-architecture model, not as the complete quality system:

- **Tutorial**: learning through a successful guided experience.
- **How-to**: completing a real task for an already-competent user.
- **Reference**: authoritative description of the system.
- **Explanation**: concepts, architecture, rationale, constraints, and tradeoffs.

Read `references/diataxis.md` when classifying or restructuring content.

## Non-negotiable: 15-minute magic path

Every external developer-facing product must have a canonical Quickstart/Get Started path where a brand-new developer with zero product knowledge can achieve and verify meaningful end-to-end product value in **15 minutes or less**.

Read `references/magic-path.md` before creating or revising onboarding, a README quickstart, installation docs, or the getting-started architecture. Read `references/standards.md` for the canonical thresholds, severity vocabulary, and release gates.

Design for the timer. Do not hide product-specific setup in prerequisites. Account creation, credentials, product-specific installation/configuration, execution, wait time, and verification count. If production provisioning cannot fit, design a sandbox/test/local path.

Installation, authentication, or a health check alone is not success. The quickstart must demonstrate the product's core value.

## Establish truth before writing

Before editing technical docs:

1. Inspect the repository and identify implementation, tests, public symbols, specs/schemas, CLI definitions, config, examples, SDKs, generated code, release metadata, and existing docs.
2. Identify the authoritative source for each normative claim.
3. Prefer implementation, tests, released interfaces, and machine-readable specifications over prose when they conflict.
4. Never invent endpoints, fields, defaults, flags, limits, status codes, environment variables, versions, behavior, or guarantees.
5. Surface contradictions explicitly.
6. Mark unknowns instead of guessing.

For broad repos, run `scripts/inventory_docs.py` when useful.

## Authoring workflow

### 1. Identify audience, state, and outcome

Determine:

- who the user is
- what they already know
- whether they are learning, working, consulting facts, or building understanding
- environment/runtime constraints
- the exact observable outcome they need

For first-run and external stakeholder docs, assume zero product-specific knowledge.

### 2. Map the developer journey

Cover the connected path:

Discover → Prerequisites → Install → Account/Auth → Configure → First value → Verify → Customize → Debug → Production → Operate → Upgrade → Get help

This list is a docs-scoped subset of the canonical 14-stage developer journey; see `references/standards.md` for the canonical stage definitions. Read `references/docs-architecture.md` for the minimum documentation system.

### 3. Classify with Diátaxis

Give each page or section one primary job. Split mixed pages when modes interfere with one another. Cross-link adjacent modes instead of combining everything into one document.

### 4. Design the magic path first

Before polishing the rest of onboarding:

1. Define the smallest meaningful end-to-end outcome.
2. Define benchmark start and stop conditions.
3. Remove optional branches and choices.
4. Choose a default SDK/language/path when the product supports many.
5. Provide test/sandbox/local resources that eliminate manual provisioning.
6. Make each command complete and copy-pasteable.
7. Show expected output or verification.
8. Budget the path to ≤15 minutes.
9. Put production hardening after first success.
10. Link advanced concepts rather than front-loading them.

If the path cannot credibly meet 15 minutes, report the blocker as Docs, Product/DX, Infrastructure, or External dependency and propose the product change required.

### 5. Review the product surface exposed by docs

When relevant, review:

- resource and method naming
- request/response shape
- HTTP semantics and status codes
- IDs, timestamps, enums, nullability, units, money
- pagination/filtering/sorting
- idempotency/retry behavior
- async operations and webhooks/events
- rate limits and quotas
- errors and remediation
- request/correlation IDs
- auth scopes and environments
- versioning/deprecation
- CLI flags, exit codes, stdout/stderr
- config precedence/defaults/secrets
- SDK ergonomics and language idioms

Read `references/api-dx.md` and `references/sdks.md` as needed.

### 6. Author the correct artifact

Read only the references relevant to the work:

- repository README: `references/readmes.md`
- quickstarts/examples: `references/examples.md` + `references/magic-path.md`
- API/CLI/protocol: `references/api-dx.md`
- SDKs: `references/sdks.md`
- public code docs/comments: `references/code-comments.md`
- stakeholder/internal docs: `references/stakeholder-docs.md`
- migrations/releases/deprecations: `references/lifecycle.md`
- terminology/style/accessibility: `references/style.md`
- coding-agent/LLM usability: `references/llm-ready-docs.md`

From devarispbrown/devex-skills, MIT.

More from devarispbrown/devex-skills