Write documentation with Diataxis (prompt)

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-documentation-with-diataxis-prompt/raw' -o ~/'.claude/skills/write-documentation-with-diataxis-prompt/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-documentation-with-diataxis-prompt/files/LICENSE.txt' -o ~/'.claude/skills/write-documentation-with-diataxis-prompt/LICENSE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-documentation-with-diataxis-prompt/raw' -o '.cursor/skills/write-documentation-with-diataxis-prompt/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-documentation-with-diataxis-prompt/files/LICENSE.txt' -o '.cursor/skills/write-documentation-with-diataxis-prompt/LICENSE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-documentation-with-diataxis-prompt/raw' -o '.agents/skills/write-documentation-with-diataxis-prompt/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/write-documentation-with-diataxis-prompt/files/LICENSE.txt' -o '.agents/skills/write-documentation-with-diataxis-prompt/LICENSE.txt'

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

Most bad docs mix four jobs on one page: teaching, solving, describing and explaining. Diataxis (diataxis.fr) splits them, so each page does one job well.

When to use

• You are starting docs for a product, API or library.
• Your docs exist but readers still cannot find answers.
• You need a reference page, an explainer or a how-to and want the right shape.

When not to use

• You only need a README. Use write-readme-prompt.
• You want one beginner walkthrough from your notes. Use write-tech-tutorial-prompt.

The four modes

| Mode | Reader is... | Page gives them | Example title |
| --- | --- | --- | --- |
| Tutorial | learning, new | a guided lesson with a sure win | "Build your first webhook" |
| How-to guide | working, has a goal | steps for one real task | "Rotate an API key" |
| Reference | looking something up | complete, dry facts | "Webhook event types" |
| Explanation | trying to understand | context, reasons, trade-offs | "Why events are retried" |

Steps

1. List the questions users ask, from support tickets, chats or issues.
2. Paste the prompt below with that list and any existing docs.
3. Approve the page plan and the mode chosen for each page.
4. Ask for one page at a time, and check every command and code sample yourself.
5. Link pages across modes: tutorials point to how-tos, how-tos point to reference.

Prompt

You are helping me write documentation using the Diataxis framework (tutorial, how-to guide, reference, explanation).

Context: [product or API], readers: [who], existing docs: [paste or "none"], user questions: [paste list].

1. If I gave you existing docs, sort each page into one mode and flag pages that mix modes.
2. Propose a page list. For each page give: title, mode, reader, the one goal it serves, and what it leaves out.
3. Ask me anything you need to know about audience, scope or product behaviour. Do not guess facts.
4. Wait for my approval. Then, for the page I pick, propose an outline and wait again.
5. Write the page in Markdown, staying in its mode:
   - Tutorial: one path, no choices, every step shows the expected result.
   - How-to: starts from a real goal, numbered steps, no teaching detours.
   - Reference: complete, consistent tables or lists, no opinions.
   - Explanation: the why, history and trade-offs, no step lists.
Use short sentences and plain words. Use fake example values for keys, tokens and passwords.
Match the tone and terms of any docs I shared, but do not copy text from them.

How to adapt

• API docs? Generate reference pages from your OpenAPI or type definitions, and hand-write only the how-tos.
• Small project? Start with one tutorial, three how-tos and one reference page.
• Internal team docs? Swap support tickets for questions from your team chat.

Gotchas

• A how-to that starts teaching concepts becomes a bad tutorial. Move the concept to an explanation page and link it.
• AI tools invent flags and endpoints. Check every command against the real product.
• Never paste real API keys, customer data or internal URLs into examples.

Portability

Works with any docs tool or static site generator, such as Docusaurus, MkDocs, Mintlify, Starlight or a plain docs folder, and with any chat AI.

Done when

• Every page has one mode, one reader and one goal.
• Commands and samples were run and use only fake secrets.
• Pages link to their neighbours in the other modes.

Example prompt

"Plan the docs for our payments API with Diataxis. Here are 20 support questions. Then write the how-to guide for refunding an order."

---

Adapted from "documentation-writer" in github/awesome-copilot (MIT, Copyright GitHub, Inc.). See LICENSE.txt.

Bundled files

• LICENSE.txt

Licence

Adapted from geoder101 (github/awesome-copilot PR #201, documentation-writer); later edits by Jrc356 and derekclair (Copyright GitHub, Inc.), MIT License. Adapted by TheSkillVault on 2026-11-02: the role-play persona was replaced by an original four-mode table, a docs-audit step and a copy-paste prompt; added steps, adapt notes, gotchas and done-when. Not the original file. Diataxis itself is by Daniele Procida (diataxis.fr).

Licence: MIT License. Attribution when you reuse it: Based on work by geoder101 (github/awesome-copilot PR #201, documentation-writer); later edits by Jrc356 and derekclair (Copyright GitHub, Inc., MIT License), https://github.com/github/awesome-copilot/tree/5269f7ea2d6c3a9bfda5ed878b6726cf509121fd/skills/documentation-writer; adapted by TheSkillVault, https://theskillvault.ai