AI Skill Report Card
Writing Technical Documentation
Quick Start14 / 15
Before writing, answer three questions:
- Audience: Who reads this? (developer, ops engineer, end user, stakeholder)
- Purpose: What must they do/know after reading?
- Scope: What's explicitly in and out of this document?
Then use this skeleton for any technical doc:
Markdown# [Title: Noun phrase describing the subject]
Recommendation▾
Add a third example showing a bad-to-good transformation for a non-API/runbook doc type (e.g., architecture decision record or user guide) to broaden coverage given the description mentions ADRs and user guides explicitly.
Overview
One paragraph: what this is, why it exists, who it's for.
[Core Content Sections]
Specifics, organized by task or component.
Examples17 / 20
Concrete usage.
Recommendation▾
Include a brief section on handling documentation maintenance/review cadence or deprecation, since 'stale examples' and 'no versioning' pitfalls are mentioned but no concrete process is given.
Reference / Appendix
Tables, edge cases, error codes.
Workflow14 / 15
Progress:
- Step 1: Define audience, purpose, scope (write this down, even if not published)
- Step 2: Outline sections as a list of questions the reader needs answered
- Step 3: Draft using active voice, present tense, numbered steps for procedures
- Step 4: Add concrete examples (real commands, real values, not placeholders like
foo/barunless illustrating syntax) - Step 5: Verify every claim is testable or sourced — no vague qualifiers
- Step 6: Self-review against the checklist below
- Step 7: Have someone unfamiliar with the subject read it, or simulate that read
Drafting Rules
- One idea per sentence. Split compound sentences describing multiple behaviors.
- Active voice, specific subject. "The server rejects the request" not "the request may be rejected."
- Define before use. Acronyms and jargon get a definition on first use.
- Numbered steps for sequences, bullets for unordered sets, tables for comparisons.
- State preconditions and postconditions for any procedure (what must be true before, what changes after).
- Quantify instead of qualifying. "Times out after 30s" not "times out quickly."
Recommendation▾
The self-review checklist step 6 references 'checklist below' but there's no explicit standalone checklist section—consolidate pitfalls/best practices into an actual pre-publish checklist for clarity.
Examples17 / 20
Example 1 — API documentation
Input: "This endpoint lets you update users, it's pretty flexible and handles most fields."
Output:
Markdownundefined
PATCH /users/{id}
Updates one or more fields of an existing user. Fields omitted from the request body are left unchanged.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | yes | User UUID |
Request body (application/json)
| Field | Type | Required | Notes |
|---|---|---|---|
| string | no | Must be unique; validated as RFC 5322 | |
| name | string | no | 1–100 characters |
Responses
200 OK— returns updated user object404 Not Found— no user with given id409 Conflict— email already in use
Example request
```bash
curl -X PATCH https://api.example.com/users/123
-H "Content-Type: application/json"
-d '{"email": "new@example.com"}'
```
**Example 2 — Runbook step**
Input: "If the service is down, restart it and check if it's working."
Output:
```markdown
### Service unresponsive on health check
**Symptom**: `/healthz` returns 503 or times out for >2 minutes.
**Procedure**:
1. Check current status: `systemctl status payment-api`
2. If status is `failed`, restart: `systemctl restart payment-api`
3. Wait 15 seconds, then verify: `curl -f http://localhost:8080/healthz`
4. If step 3 returns `200`, incident is resolved — log in #incidents.
5. If step 3 still fails, escalate to on-call (see [Escalation Policy](#)).
**Do not** restart more than twice without escalating — repeated restarts
without root-cause analysis can mask data corruption issues.
Best Practices
- Write the title as a noun phrase that could stand alone in a table of contents.
- Put the most important information first (inverted pyramid); details and edge cases later.
- Use consistent terminology — pick one term per concept and never swap synonyms in.
- Include a "Last updated" or version marker on living documents.
- Prefer diagrams/tables over prose when describing structure, flow, or comparisons.
- Link to source of truth (code, config) instead of duplicating values that will drift.
- Review for the inverse: does this document answer the error case, not just the happy path?
Common Pitfalls
- Vague qualifiers: "fast," "often," "usually," "should work" — replace with numbers, conditions, or explicit guarantees.
- Undefined jargon: don't assume the reader shares your acronym vocabulary.
- Missing preconditions: a procedure that assumes undocumented prior state will fail for readers.
- Mixing audiences: don't interleave end-user instructions with internal implementation detail — split into separate docs.
- Stale examples: untested code samples rot; verify examples actually run before publishing.
- Passive voice hiding responsibility: "errors are logged" — by what, where? Say "the service writes errors to
/var/log/app.log." - No versioning: documentation for a system without API/version changes noted becomes misleading silently.