writing-documentation

Diátaxis organizes documentation into four types—Tutorial, How-To, Reference, and Explanation—each serving a distinct user need. Tutorials teach through hands-on tasks; How-Tos solve specific problems; References provide quick lookup; Explanations build conceptual understanding. This framework ensures your documentation matches how users actually search for and consume information.

API reference documentation should follow the Reference format: list endpoints, parameters, return values, and error codes with concise, scannable descriptions. Include runnable examples and organize by logical grouping. This Skill applies Diátaxis patterns to generate production-ready API guides faster, reducing iteration cycles and ensuring consistency across microservices.

Apply explicit quality safeguards: test Claude's base knowledge, document unique conventions, trim boilerplate, and review for security risks and misinterpretation. This Skill embeds these guardrails into a semantic prompt, preventing hallucinations and ensuring documentation is accurate and production-ready before publication.

Yes. Apply Diátaxis principles to code comments: use Explanation style for complex logic, How-To for common patterns, and Reference style for function signatures. This Skill generates compact prompts that capture documentation discipline for API guides, tutorials, and inline code references across formats.

Vector embedding enables RAG workflows to retrieve the right documentation section when users query an LLM. This Skill generates high-density semantic prompts optimized for embedding, so your documentation integrates seamlessly into retrieval-augmented systems and improves search accuracy.

No. Start by outlining your problem, selecting a Diátaxis type (Tutorial, How-To, Reference, Explanation), drafting sections, and adding a Quick Start example. This Skill provides structured guidance; Diátaxis patterns handle the heavy lifting, reducing expertise required to produce clear, consistent technical docs.