Skip to main content

Documentation & Content Creation Workflow

Generate high-quality documentation and technical content efficiently

Use Ada CLI to create, update, and maintain documentation ranging from API references to beginner tutorials.

API Documentation Generation

Automated API Docs

Generate comprehensive API documentation from code:

bash
# Full API documentation
ada agents run docs-generator "Generate complete API documentation" --input ./src/api --output ./docs/api

# OpenAPI/Swagger spec
ada chat "Generate OpenAPI 3.0 specification from Express routes" --context ./src/routes

# Endpoint documentation
ada chat "Document this API endpoint with parameters, responses, and examples" --context ./src/api/users.ts

Interactive API Examples

Create executable examples:

bash
# Request/response examples
ada chat "Generate curl examples for all user API endpoints"

# SDK usage examples
ada chat "Create JavaScript SDK examples for user management API"

# Postman collection
ada chat "Generate Postman collection JSON for the API"

Expected Output: Complete API reference, usage examples, integration guides.

README Creation

Project README

Create compelling project documentation:

bash
# Comprehensive README
ada chat "Create README.md covering installation, usage, features, and contributing" --context ./

# Quick start section
ada chat "Write a 'Quick Start' section for the README with copy-paste commands"

# Feature showcase
ada chat "Create 'Features' section highlighting key capabilities with code examples"

README Sections

Generate specific sections:

bash
# Installation instructions
ada chat "Write installation section supporting npm, yarn, and pnpm"

# Usage examples
ada chat "Create 5 usage examples from basic to advanced"

# Troubleshooting section
ada chat "Generate troubleshooting section for common issues"

# Contributing guide
ada chat "Write contributing section with development setup and PR process"

Expected Output: Professional README, clear setup instructions, engaging examples.

Tutorial Writing

Step-By-Step Tutorials

Create beginner-friendly guides:

bash
# Tutorial planning
ada chat "Create tutorial outline for 'Building a REST API with Express and Prisma'"

# Write tutorial
ada agents run tutorial-generator "Write complete beginner tutorial for Express + Prisma API" --output ./tutorials/getting-started.md

# Add screenshots
ada chat "Describe screenshots needed for each tutorial step"

Code Walkthroughs

Explain code in depth:

bash
# Annotated code
ada chat "Create annotated version of this code explaining each section" --context ./auth-service.ts

# Concept explanation
ada chat "Write explanation of how authentication flow works in this codebase" --context ./src/auth

# Best practices guide
ada chat "Create best practices guide based on patterns in this codebase" --context ./src

Expected Output: Clear tutorials, helpful walkthroughs, practical learning resources.

Architecture Documentation

System Overview

Document high-level architecture:

bash
# Architecture overview
ada chat "Create ARCHITECTURE.md explaining system design and components" --context ./src

# Component descriptions
ada chat "Document each major component's purpose and interactions"

# Data flow diagrams
ada chat "Describe data flow diagrams for: user registration, API request handling, background jobs"

Technical Decisions

Record architectural choices:

bash
# ADR creation
ada chat "Create Architecture Decision Record for choosing Prisma over TypeORM"

# Technology rationale
ada chat "Document why we chose Next.js for this project"

# Design patterns
ada chat "Document design patterns used in this codebase and their benefits" --context ./src

Expected Output: Clear architecture docs, decision records, system diagrams.

Code Comments & JSDoc

Automated Code Documentation

Add helpful code comments:

bash
# JSDoc generation
ada chat "Add comprehensive JSDoc comments to this file" --context ./utils.ts

# Complex function explanation
ada chat "Add detailed comments explaining this algorithm" --context ./sort-algorithm.ts

# Type documentation
ada chat "Document these TypeScript types with usage examples" --context ./types.ts

Inline Documentation

Improve code readability:

bash
# Add comments
ada chat "Add inline comments explaining complex logic" --context ./parser.ts

# Document edge cases
ada chat "Add comments documenting edge cases and error handling"

# Usage examples in comments
ada chat "Add usage example comments to public functions"

Expected Output: Well-commented code, clear type documentation, helpful examples.

User Guides

End-User Documentation

Create documentation for non-technical users:

bash
# User guide
ada chat "Write user guide for the dashboard feature"

# FAQ creation
ada chat "Generate FAQ based on common support questions"

# Feature documentation
ada chat "Document how to use the team collaboration features"

Admin Documentation

Document administrative features:

bash
# Admin guide
ada chat "Create administrator guide for managing users and permissions"

# Configuration reference
ada chat "Document all configuration options with examples"

# Troubleshooting playbook
ada chat "Create troubleshooting playbook for common admin tasks"

Expected Output: Clear user documentation, helpful FAQs, admin resources.

Documentation Maintenance

Updating Existing Docs

Keep documentation current:

bash
# Identify outdated docs
ada chat "Review README.md and identify outdated information" --context ./README.md

# Update for changes
ada chat "Update API documentation to reflect new authentication endpoints" --context ./docs/api.md

# Changelog generation
ada chat "Generate CHANGELOG entry for recent changes" --context ./git log

Consistency Checks

Ensure documentation quality:

bash
# Style consistency
ada chat "Review docs for style consistency and suggest improvements" --context ./docs

# Completeness check
ada chat "Identify missing documentation for public APIs" --context ./src/api

# Link validation
ada chat "List all documentation links and check for broken references"

Expected Output: Up-to-date docs, consistent style, complete coverage.

Blog Posts & Articles

Technical Blog Posts

Write about your project:

bash
# Blog post outline
ada chat "Create outline for blog post: 'Building a Scalable API with Node.js and Prisma'"

# Write blog post
ada agents run content-generator "Write technical blog post explaining our API architecture" --input ./src/api --output ./blog/api-architecture.md

# Code snippets
ada chat "Extract interesting code snippets from this project for blog post"

Case Studies

Document project journeys:

bash
# Case study outline
ada chat "Create case study outline for: How we scaled to 1M users"

# Technical challenges
ada chat "Document technical challenges and solutions from this project"

# Lessons learned
ada chat "Write 'lessons learned' section based on project experience"

Expected Output: Engaging blog content, technical case studies, shareable insights.

Documentation Organization

Documentation Structure

Organize docs effectively:

bash
# Documentation inventory
ada chat "List all documentation files and suggest better organization"

# Structure proposal
ada chat "Propose documentation structure for: guides, references, tutorials"

# Navigation creation
ada chat "Create docs navigation sidebar with logical grouping"

Documentation Templates

Create reusable templates:

bash
# README template
ada chat "Create README template for new projects"

# API endpoint template
ada chat "Create template for documenting API endpoints"

# Tutorial template
ada chat "Create step-by-step tutorial template"

Expected Output: Organized documentation, findable information, consistent templates.

Complete Documentation Sprint

Example workflow for comprehensive documentation:

bash
# Day 1: Planning
ada chat "Audit current documentation and create improvement plan" --context ./docs
ada chat "Prioritize documentation tasks by user impact"

# Day 2: API Documentation
ada agents run docs-generator --input ./src/api --output ./docs/api-reference.md
ada chat "Add usage examples to API documentation"

# Day 3: Guides & Tutorials
ada agents run tutorial-generator "Getting Started tutorial" --output ./docs/getting-started.md
ada chat "Create user guide for key features"

# Day 4: Architecture & Technical Docs
ada chat "Create ARCHITECTURE.md" --context ./src
ada chat "Write ADRs for major technical decisions"

# Day 5: Polish & Review
ada chat "Review all documentation for consistency" --context ./docs
ada chat "Generate comprehensive README.md" --context ./
ada chat "Create CONTRIBUTING.md for open source"

Documentation Best Practices

Writing Style

Create clear, accessible documentation:

bash
# Simplify language
ada chat "Review this doc and simplify technical jargon" --context ./guide.md

# Improve clarity
ada chat "Rewrite this section for better clarity" --context ./docs/setup.md

# Add examples
ada chat "Add practical examples to this documentation" --context ./README.md

Accessibility

Make docs inclusive:

bash
# Plain language
ada chat "Rewrite for non-native English speakers" --context ./docs

# Beginner-friendly
ada chat "Add definitions for technical terms"

# Visual aids
ada chat "Suggest diagrams and screenshots to add"

Expected Output: Clear, accessible documentation, inclusive language, helpful visuals.

Related Workflows

Start documenting: ada chat "Help me create documentation for [project]"