Documentation Writer

Software documentation requires consistent structure, clear explanations, and comprehensive coverage of features, APIs, and usage patterns. This skill generates technical documentation following established standards, creating API references, user guides, architecture documents, and README files with proper formatting, code examples, and organized sections.

What Is This?

Overview

Documentation Writer generates technical documentation for software projects following documentation best practices and standards. It creates API documentation with endpoint specifications, user guides with step-by-step instructions, architecture documentation explaining system design, README files for repositories, code comments and docstrings, and tutorial content with working examples.

The skill understands various documentation formats including Markdown, reStructuredText, JSDoc, and Sphinx, follows documentation frameworks like Diátaxis (tutorials, how-to guides, reference, explanation), and ensures consistency in tone, structure, and formatting across documentation sets.

This produces professional documentation efficiently without manual formatting and organization work, ensuring projects have comprehensive documentation users and developers need.

Who Should Use This

Software developers documenting codebases. Technical writers creating user guides. API developers needing endpoint documentation. Open source maintainers writing README files. Teams requiring architecture documentation. Anyone needing structured technical documentation.

Why Use It?

Problems It Solves

Documentation is time-consuming and often neglected. Automated generation produces comprehensive docs quickly ensuring projects aren't undocumented.

Inconsistent documentation structure makes information hard to find. Standardized formats ensure users can navigate docs predictably.

Technical writing requires specific skills many developers lack. Generated documentation follows best practices improving quality and clarity.

Keeping documentation synchronized with code is challenging. Structured generation from code and specifications ensures accuracy.

Core Highlights

API documentation with endpoint specifications. User guides with step-by-step instructions. Architecture documentation explaining design. README file generation for repositories. Code comments and docstrings. Tutorial content with examples. Multiple format support (Markdown, RST, JSDoc). Diátaxis framework following. Consistent formatting and structure.

How to Use It?

Basic Usage

Specify documentation type needed and provide codebase or API information. The skill generates structured documentation.

Generate API documentation for REST endpoints

Create user guide for CLI tool

Write README for open source library

Specific Scenarios

For API documentation:

Document GraphQL schema with queries and mutations

For architecture docs:

Create architecture document explaining microservices design

For tutorials:

Write tutorial for getting started with the framework

Real-World Examples

An API team needs comprehensive endpoint documentation. They provide OpenAPI specification. The skill generates documentation with endpoint descriptions, request/response examples, authentication requirements, error codes, and rate limiting information formatted as a reference guide developers can search easily.

An open source project needs a professional README. The maintainer provides project description, installation steps, and usage examples. The generated README includes badges, clear sections, code examples with syntax highlighting, contribution guidelines, and license information following community standards.

A team needs to document their microservices architecture for new engineers. They describe services, communication patterns, and data flows. The skill generates architecture documentation with system diagrams, service responsibilities, API contracts, deployment topology, and operational considerations structured for easy onboarding.

Advanced Tips

Follow Diátaxis framework separating tutorials, how-to guides, reference, and explanation. Include working code examples that can be copy-pasted. Use consistent terminology across documentation. Add diagrams for complex concepts. Document not just what but why decisions were made. Keep documentation versioned with code. Update docs when code changes. Test code examples before publishing.

When to Use It?

Use Cases

API documentation for web services. User guides for applications. README files for repositories. Architecture documentation for systems. Tutorial content for learning. Code comment generation. Migration guides for version updates. Troubleshooting guides for common issues.

Related Topics

Documentation frameworks (Diátaxis, Divio). Technical writing best practices. API documentation standards (OpenAPI, GraphQL). Markdown and reStructuredText formats. Documentation generators (Sphinx, JSDoc, Docusaurus). Documentation hosting platforms.

Important Notes

Requirements

Clear understanding of what needs documentation. Access to codebase or API specifications. Knowledge of target audience and their needs. Code examples that work correctly. Understanding of documentation purpose (reference vs tutorial).

Usage Recommendations

Follow Diátaxis framework for structure. Include practical code examples. Use consistent terminology. Add visual diagrams where helpful. Document assumptions and prerequisites. Keep documentation versioned with code. Test all code examples. Update documentation when functionality changes. Organize content for easy navigation.

Limitations

Generated documentation needs review for accuracy. Cannot document features without clear specifications. Code examples require verification. Quality depends on input completeness. Cannot replace human understanding of user needs. Works best for standard documentation patterns. May need customization for specific audiences.