doc-writing
npx machina-cli add skill VidyFoo/antigravity-skill-engine/doc-writing --openclawDocumentation Engineering
Purpose
Code tells you how. Documentation tells you why and what. We treat documentation as an engineering artifact: structured, versioned, and maintained.
When to Use This Skill
- New Project: "Write a README."
- Knowledge Transfer: "Explain how this works."
- API: "Document this endpoint."
- Handover: "Create a user guide."
Core Framework: Diátaxis
Classify your document into one of four quadrants to ensure clarity.
- Tutorials (Learning-oriented): A lesson to get a beginner started.
- Example: "Build your first Todo App in 5 minutes."
- Tone: Inspiring, step-by-step, no choices (follow me).
- How-to Guides (Problem-oriented): A recipe to solve a specific problem.
- Example: "How to reset your password."
- Tone: Practical, concise, steps 1-2-3.
- Reference (Information-oriented): Technical description of machinery.
- Example: "User API Class Specification."
- Tone: Dry, accurate, complete.
- Explanation (Understanding-oriented): Context and background.
- Example: "Why we chose Rust over C++."
- Tone: Discursive, theoretical.
Google Style Guide Highlights
- Voice: Active, not passive. ("Click the button", not "The button should be clicked").
- Second Person: Speak to "you" (the user).
- Simplicity: Use short sentences and plain language.
Resource Files
| Topic | File |
|---|---|
| Framework Deep Dive | diataxis.md (Understanding the 4 types) |
| README Standard | readme-template.md (The Gold Standard) |
| Style Checklist | style-guide.md (Writing rules) |
Source
git clone https://github.com/VidyFoo/antigravity-skill-engine/blob/main/.agent/skills/4-tools/doc-writing/SKILL.mdView on GitHub Overview
Treat documentation as an engineering artifact: structured, versioned, and maintained. This skill helps you create, maintain, and structure clear technical documentation for projects, APIs, and handovers, with outputs in PDF, DOCX, XLSX, and PPTX.
How This Skill Works
Classify documents into the four Diátaxis quadrants (Tutorials, How-to Guides, Reference, Explanation) to define purpose and tone. Write following the Google Style Guide to keep voice active, use second person, and favor simplicity, then leverage templates like diataxis.md, readme-template.md, and style-guide.md, exporting to common formats as needed.
When to Use It
- New Project: Write a README.
- Knowledge Transfer: Explain how this works.
- API: Document this endpoint.
- Handover: Create a user guide.
- Documentation maintenance: Update and version existing docs.
Quick Start
- Step 1: Determine the audience and select the appropriate Diátaxis quadrant.
- Step 2: Draft the doc sections aligned to the quadrant and apply the Google Style Guide.
- Step 3: Export to PDF, DOCX, XLSX, or PPTX and store in versioned templates.
Best Practices
- Classify docs into Diátaxis quadrants to clarify purpose and tone.
- Follow Google Style Guide: use active voice, address the user directly, and keep sentences short.
- Leverage provided templates (diataxis.md, readme-template.md, style-guide.md) for consistency.
- Write with clear steps or structured sections appropriate to the quadrant.
- Maintain versioned, organized artifacts and reuse templates for new docs.
Example Use Cases
- Build your first Todo App in 5 minutes.
- How to reset your password.
- User API Class Specification.
- Why we chose Rust over C++.
- Document this endpoint.
