technical-writing

Apply the Diataxis framework and interface-element template to write software documentation.

Updated May 10, 2026
One-click install
npx skills add https://github.com/rob-broadley/ai-airbase --skill technical-writing-rob-broadley
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: technical-writing
Source: https://github.com/rob-broadley/ai-airbase/tree/main/cadre/skills/technical-writing
Command: npx skills add https://github.com/rob-broadley/ai-airbase --skill technical-writing-rob-broadley

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It solves the problem of documentation that feels confusing, incomplete, or hard to navigate by enforcing clear document types, consistent reference patterns, and minimum coverage standards so readers can find answers without asking.

Core Features & Use Cases

  • Diataxis document-type framework: Guides you to choose exactly one of Tutorial, How-to, Reference, or Explanation so each document has a single purpose and the right structure for its reader.
  • Interface-element reference template: Standardizes how you document every CLI subcommand, API endpoint, config option, or similar element using consistent questions for identity, inputs, outputs, failure modes, and examples.
  • Coverage standards for real readers: Ensures a new user can answer what the project does, how to install or access it, what minimal success looks like, how to use the primary interface, and how to contribute or develop locally.
  • Practical writing principles: Improves clarity with audience-first planning, active voice, imperative instructions, present-tense descriptions, progressive disclosure, and concrete examples.

Quick Start

Load technical-writing before drafting or updating any documentation, then classify each document with Diataxis and fill in the interface-element template for every user-facing option or workflow.

Frequently Asked Questions about technical-writing

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure software documentation so readers can actually find answers?

To structure software documentation effectively, apply the Diataxis framework to classify each document as a Tutorial, How-to, Reference, or Explanation. This ensures every document has a single purpose and the right structure for its reader.

What is the best way to write a README that covers all necessary project information?

The best way to write a README is to enforce minimum coverage standards: what the project does, how to install or access it, what minimal success looks like, how to use the primary interface, and how to develop locally. This ensures a new user can get started without asking for help.

How do I document API endpoints and CLI flags consistently?

Document API endpoints and CLI flags consistently by using a standardized interface-element reference template. This template requires precise sections for identity, inputs, outputs, failure modes, and verified examples for every user-facing configuration option.

Does the Diataxis framework work for troubleshooting and user onboarding documentation?

Yes, the Diataxis framework works for troubleshooting and user onboarding by guiding you to choose exactly one of Tutorial, How-to, Reference, or Explanation. This applies directly to README writing, reference sections, and documentation updates across workflows.

What writing principles improve technical clarity in reference documentation?

Technical clarity in reference documentation improves by applying audience-first planning, active voice, imperative instructions, present-tense descriptions, progressive disclosure, and concrete examples. These principles ensure readers can navigate complex interface documentation without confusion.