technical-docs
Write API references, user guides, setup manuals and architecture docs with consistent terminology. Use when writing developer documentation, API guides, or tutorials.
- License 许可
- MIT
- 最近更新
- 2026-10-02
- Stars
- ★ 0
- Forks
- 2
01 前言 Front Matter
- name
- technical-docs
- group
- Documents
- description
- Write API references, user guides, setup manuals and architecture docs with consistent terminology. Use when writing developer documentation, API guides, or tutorials.
- last_reviewed
- 1788652800000
02 资源文件 2
- 参考文档evals/routing.yaml1.0 KB
- 其他technical-docs.skill3.5 KB
03 SKILL.md 正文
Technical Docs
Technical documentation serves four distinct modes (the Divio framework: Tutorials, How-To Guides, Reference, and Explanation). Documentation fails when these modes blur — such as when setup tutorials detour into deep architecture, or when API reference pages lack reproducible request and response payloads.
Process
- Classify documentation intent (Tutorial, How-To, Reference, or Architectural Explanation).
- Establish reader prerequisites, environment requirements, and required tokens/keys.
- Structure procedures with sequential, imperative, single-action steps.
- Provide complete, runnable code examples with expected output.
- Standardize domain terminology in a structured glossary.
Output Format
Technical Documentation: [Topic]
Overview
[One-paragraph plain English summary of what this component accomplishes and why it exists]
Prerequisites
- Node.js >= 20.0.0 or Python >= 3.11
- Environment variable
API_KEYconfigured in.env
Quickstart / How-It-Works
- Step 1: Install Dependencies:
npm install @company/sdk - Step 2: Initialize Client:
import { Client } from "@company/sdk"; const client = new Client({ apiKey: process.env.API_KEY }); - Step 3: Execute Operation:
const res = await client.resources.get("id_123"); console.log(res.data);
API Reference / Schema
- Endpoint:
POST /api/v1/resources - Headers:
Authorization: Bearer <token>,Content-Type: application/json - Request Body:
{ "name": "sample", "tier": "standard" } - Response
201 Created:{ "id": "res_987", "status": "active" }
Glossary & Terminology
| Term | Definition | Context / Scope |
|---|---|---|
| Idempotency Key | Unique header to prevent duplicate charge execution | All mutation endpoints |
| Tenant ID | UUID representing the client organization partition | Multi-tenant auth token |
Audience-First Writing
Before writing: Who is reading this and what do they already know?
- Developer docs: Technical terms OK, code examples, values precision
- End-user guides: Minimal technical knowledge assumed, task-oriented, screenshots
- Executive summaries: No technical detail, focus on business outcomes
Documentation Types (Divio System)
- Tutorials: Learning-oriented, hold reader's hand to first success
- How-to Guides: Goal-oriented, step-by-step for known goals
- Reference: Information-oriented, complete and accurate, dense
- Explanations: Understanding-oriented, background and context
Style Rules
Active voice, one action per step, consistent terminology, test your own instructions.
Critical rules
- Prefer concrete, actionable steps over vague advice — the user needs executable output.
- Ask for missing context only when it blocks a correct answer; otherwise state assumptions.
- Do not invent personal identities, third-party credits, or external source claims.
Additional notes (merged)
- Write README files that make developers want to use a project within the first 30 seconds
- Create API reference docs that are complete, accurate, and include working code examples
- Build step-by-step tutorials that guide beginners from zero to working in under 15 minutes
- Write conceptual guides that explain why, not just how
- Set up documentation pipelines using Docusaurus, MkDocs, Sphinx, or VitePress
- Automate API reference generation from OpenAPI/Swagger specs, JSDoc, or docstrings
- Integrate docs builds into CI/CD so outdated docs fail the build
- Maintain versioned documentation alongside versioned software releases
- Audit existing docs for accuracy, gaps, and stale content
- Define documentation standards and templates for engineering teams
- Create contribution guides that make it easy for engineers to write good docs
- Measure documentation effectiveness with analytics, support ticket correlation, and user feedback
- Code examples must run — every snippet is tested before it ships
- No assumption of context — every doc stands alone or links to prerequisite context explicitly
- Keep voice consistent — second person ("you"), present tense, active voice throughout
- Version everything — docs must match the software version they describe
- One concept per section — do not combine installation, configuration, and usage into one wall of text
- Lead with the result the user asked for.
- Use clear headings and bullet lists where helpful.
- Call out assumptions and open questions at the end.
- Stay specific to the Technical Writer workflow; avoid generic filler.
Verification & Quality Checklist
- [ ] Every factual claim and statistic traced to a citable source.
- [ ] Reading level and terminology matched to the stated audience.
- [ ] Length and formatting fit the destination channel's limits.
- [ ] One clear call to action, placed where the reader will still be reading.
Anti-Patterns & Constraints
- NEVER invent statistics, quotes, or sources.
- NEVER present an unverified figure as sourced.
- NEVER bury the central point below preamble the reader will not reach.
04 同仓库更多 Skills
writing-taste
暂无简介
translation
Translate while preserving register, idiom and domain terms, flagging what doesn't carry across. Use when translating text across languages preserving nuance, tone, and idioms.
thread-to-blog-converter
Moved to modernized catalog in skillary. Removed in v4.1.
thread-to-article
Expand an X or LinkedIn thread into a structured article with added context, headings and links. Use when expanding social threads into long-form articles, or vice versa.
technical-writer
Moved to technical-docs in skills-writing. Removed in v4.1.
talk-writing
Write a conference talk or keynote: through-line, one idea per slide, opening hook and honest timing. Use when scripting keynote talks, conference presentations, or lightning talks.