playbooks

home / skills / a5c-ai / babysitter / diataxis-doc-generator

diataxis-doc-generator skill

/plugins/babysitter/skills/babysit/process/specializations/sdk-platform-development/skills/diataxis-doc-generator

This skill generates Diataxis-compliant documentation including tutorials, how-tos, references, and explanations to improve developer learning and onboarding.

npx playbooks add skill a5c-ai/babysitter --skill diataxis-doc-generator

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.0 KB
---
name: diataxis-doc-generator
description: Generate documentation following the Diataxis framework
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
---

# Diataxis Documentation Generator Skill

## Overview

This skill generates comprehensive documentation following the Diataxis framework, organizing content into tutorials, how-to guides, reference, and explanation categories for optimal developer learning.

## Capabilities

- Structure documentation as tutorials, how-to guides, reference, explanation
- Generate progressive getting started guides
- Create interactive API reference documentation
- Build code example repositories with multiple languages
- Implement documentation versioning
- Configure search and navigation
- Generate documentation from code comments
- Support multiple documentation platforms

## Target Processes

- API Documentation System
- SDK Onboarding and Tutorials
- Developer Experience Optimization

## Integration Points

- Docusaurus for React-based docs
- ReadTheDocs for Python projects
- Mintlify for modern documentation
- GitBook for collaborative docs
- MDX for interactive components

## Input Requirements

- API specification or source code
- Target audience profiles
- Documentation platform preference
- Branding and style guidelines
- Code example requirements

## Output Artifacts

- Structured documentation site
- Tutorial sequences
- How-to guide collection
- API reference pages
- Explanation articles
- Code examples repository
- Navigation configuration

## Usage Example

```yaml
skill:
  name: diataxis-doc-generator
  context:
    apiSpec: ./openapi.yaml
    platform: docusaurus
    languages:
      - javascript
      - python
      - curl
    includePlayground: true
    versioning: true
```

## Best Practices

1. Separate learning-oriented from task-oriented content
2. Keep tutorials focused on learning, not completeness
3. Make how-to guides goal-oriented
4. Ensure reference is accurate and complete
5. Write explanations to deepen understanding
6. Include runnable code examples

Overview

This skill generates developer documentation organized with the Diataxis framework: tutorials, how-to guides, reference, and explanations. It produces structured sites, versioned API references, and runnable code examples tailored to audience and platform preferences. The output focuses on learnability and task completion for SDKs, APIs, and developer tools.

How this skill works

The skill ingests an API specification or source code plus audience, platform, and style inputs. It classifies content into Diataxis categories, generates progressive tutorials, goal‑oriented how‑tos, precise reference pages, and explanation articles. It can scaffold multi‑language examples, configure navigation and search, and emit platform-specific artifacts for Docusaurus, ReadTheDocs, GitBook, or MDX.

When to use it

  • Onboard users to a new SDK or API with step-by-step tutorials
  • Convert an OpenAPI spec or annotated codebase into a searchable reference site
  • Create goal-driven how-to articles for common developer tasks
  • Add explanatory background articles to reduce support load
  • Publish multi-language code examples and interactive playgrounds

Best practices

  • Separate learning content (tutorials/explanations) from task content (how‑tos/reference)
  • Scope tutorials to teach a single workflow or concept per sequence
  • Keep reference pages factual, minimal, and copy‑pasted runnable when possible
  • Write how‑tos as goal → steps → verification with examples
  • Include versioning and changelogs so docs match released APIs

Example use cases

  • Generate an SDK onboarding flow with sample projects in JavaScript and Python
  • Produce an interactive API reference site from an OpenAPI file with try-it playgrounds
  • Create a how‑to collection that solves frequent customer integration tasks
  • Build explanation articles that describe core design patterns and trade-offs
  • Scaffold docs for a product launch with navigation, search, and versioning configured

FAQ

What inputs does the generator need?

An API spec or source code, target audience profile, preferred documentation platform, style guidelines, and desired example languages.

Can it produce runnable code examples?

Yes. It can generate multi‑language examples, repo scaffolds, and integrate interactive playgrounds when supported by the target platform.