# Technical Doc Writer

> Guide for creating effective, structured, and token-efficient technical documentation. Use when taking on documentation tasks, defining system architecture, writing technical specs, or whenever the user asks for "structured documentation". Use when this capability is needed.

- Skill: `tomevault-io/technical-doc-writer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/technical-doc-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/technical-doc-writer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/technical-doc-writer

---


# Technical Documentation Writer

This skill empowers you to produce technical documentation that is:
* **Effective**: Clear, actionable, and comprehensive.
* **Structured**: Organized logically into easy-to-navigate modular files.
* **Token-Efficient**: Optimized for consumption by both Humans and AI Agents.

## When to Use This Skill
- Initializing documentation for a new project.
- Refactoring existing "monolithic" documentation into a modular structure.
- Documenting specific system components (Architecture, API, Database, etc.) following a standard schema.

## The Standard Structure

We adopt a modular "folders and subfolders" approach to keep context focused and manageable. This is similar to the modular skill structure itself. This creates a "Knowledge/Documentation Graph" where each node (file) has a specific purpose.

### Core Sections
See the bundled script for the canonical list, but generally:
1.  **Architecture**: System review, tech stack, diagrams.
2.  **Database**: Schemas, relationships.
3.  **API**: Endpoints, contracts.
4.  **Security**: Auth, compliance.
5.  **Operations**: Deployment, monitoring, logging.
6.  **Quality**: Testing strategies.
7.  **Edge Cases**: Specific handling of non-happy paths.

## Workflow

### 1. Scaffold the Structure
Don't worry about creating files manually. Use the bundled script to generate the standard folder and file structure.

**Command:**
```bash
python3 .agent/skills/technical-doc-writer/scripts/scaffold_docs.py <target_directory>
```
*Example: `python3 .agent/skills/technical-doc-writer/scripts/scaffold_docs.py docs/technical`*

### 2. Populate the Content
Iterate through the generated files. You do not need to fill them all at once. Priorities usually are:
1.  System Architecture & Database Schema (The Foundation)
2.  API Specifications & Integration (The Interface)
3.  Others as implementation details solidify.

### 3. Writing Guidelines for Token Efficiency

*   **Use Mermaid Diagrams**: Instead of long textual descriptions of flows, use `mermaid` diagrams.
*   **Lists over Paragraphs**: Use bullet points for features, requirements, and steps.
*   **Link, Don't Duplicate**: If a concept is defined in `01_system_architecture.md`, reference it in other files rather than redefining it.
*   **Consistent Headers**: Stick to the provided headers in the templates.
*   **Data over Prose**: For schemas and APIs, prefer table formats or code blocks (JSON/SQL) over descriptive text.

## Resources
- **Script**: `scripts/scaffold_docs.py` - Automates the creation of the documentation folder and markdown skeletons.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/radema) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->