cratis-documentation-writing

Write and structure documentation pages using the Diátaxis framework with runnable examples.

3|Updated Dec 25, 2024
One-click install
npx skills add https://github.com/Cratis/Samples --skill cratis-documentation-writing-cratis
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: cratis-documentation-writing
Source: https://github.com/Cratis/Samples/tree/main/.cratis/ai/skills/cratis-documentation-writing
Command: npx skills add https://github.com/Cratis/Samples --skill cratis-documentation-writing-cratis

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Documentation often fails because pages mix teaching, instruction, reference, and explanation into one unfocused document. This Skill classifies each page into the correct Diátaxis type (Tutorial, How-to guide, Reference, or Explanation) and enforces the structure, voice, and code-example standards that make documentation actually serve its readers. ## Core Features & Use Cases - Diátaxis Classification: Decide whether a page is a Tutorial, How-to guide, Reference, or Explanation before drafting, with per-type rules that prevent mixing concerns. - Structured Writing Workflow: Follow a four-step process — clarify audience and scope, propose an outline, write the full page, then verify against a completion checklist. - Style and Example Standards: Enforce active voice, second person, American English, complete runnable code examples, and Mermaid diagrams for architecture and flows. - Use Case: When adding a new feature to a Cratis-based project, use this Skill to draft a how-to guide showing users the exact steps, with a complete working code example and links to related reference pages. ## Quick Start Ask the assistant to write a how-to guide for configuring a feature in your Cratis project, following the Diátaxis documentation standards.

Frequently Asked Questions about cratis-documentation-writing

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

FAQPage Schema
How do I decide between a tutorial and a how-to guide?▼

A tutorial guides a newcomer step-by-step to a first successful outcome without explaining why, while a how-to guide shows an experienced user how to accomplish a specific task. Choose based on whether your reader is learning or solving a problem.

What is the Diátaxis framework for documentation?▼

Diátaxis separates documentation into four types — tutorials, how-to guides, reference, and explanation — each serving one distinct user need. The framework forbids mixing types in a single page, since a page that teaches, instructs, and explains at once serves none of those needs well.

Can I use this documentation approach outside a docs site?▼

Yes, the skill is documentation-system-agnostic and applies to a docs site, a docs folder in a repository, a wiki, or README files. It governs classification, structure, and prose, while navigation and page placement follow your project's own conventions.

Why should documentation code examples avoid copying from the repository?▼

Copied code drifts out of sync as APIs change, breaking the examples silently. The skill requires purpose-built examples that are complete, runnable, and demonstrate exactly the documented behavior, with the expected output shown for verification.

When should I not use this documentation writing skill?▼

Do not use it for code generation, release operations, or inventing API facts the code does not show. It is strictly for writing and restructuring documentation pages, not for producing implementation code or speculating about undocumented behavior.