diataxis

name

diataxis

description

Write documentation for the Conjecture .NET library following the Diataxis framework (https://diataxis.fr/). Use this skill whenever the user wants to write, update, or reorganize docs — tutorials, how-to guides, reference material, or explanation/background pages — for the Conjecture project. Triggers on: "write a tutorial for X", "document X", "write a how-to for X", "explain why X works this way", "reorganize the docs", "add docs for X", "reference docs for X", or any request to produce DocFX markdown for the docs/site/ tree. Also use proactively when a new feature is implemented and docs haven't been written.

Diataxis Documentation Skill

Produce documentation for the Conjecture .NET library in DocFX-flavored Markdown, structured according to the Diataxis framework. Each doc type has a different purpose, audience mindset, and structure — pick the right one before writing.

Step 1: Determine the quadrant

User asks for…	Quadrant	Reader's mindset
Tutorial, walkthrough, "getting started with X"	Tutorial	Learning by doing
How do I…, step-by-step, recipe for X	How-to	Solving a specific problem
API docs, parameters, types, what does X accept	Reference	Consulting facts
Why does X work this way, background, concept explanation	Explanation	Building understanding

When the intent is ambiguous, ask. Getting the quadrant wrong produces docs that confuse readers even when technically accurate.

Read the quadrant guide before writing:

• Tutorial → references/tutorial.md
• How-to → references/how-to.md
• Reference → references/reference.md
• Explanation → references/explanation.md

Step 2: Understand what exists

Before writing, read:

1. The relevant existing doc files in docs/site/articles/ — understand what's already there
2. The applicable toc.yml — know where the new file fits
3. The source code for the feature being documented — read the public API surface (PublicAPI.Unshipped.txt and the relevant .cs files)
4. The ADR in docs/decisions/ if one exists for the feature

Step 3: Write the doc

Follow the quadrant guide. Also apply these project-wide conventions:

DocFX conventions

Framework tabs — use whenever showing code that differs across test frameworks:

# [xUnit v2](#tab/xunit-v2)
...code...
# [xUnit v3](#tab/xunit-v3)
...code...
# [NUnit](#tab/nunit)
...code...
# [MSTest](#tab/mstest)
...code...
***

Cross-references — use relative links: [Installation](../installation.md), [API](../../api/Conjecture.Core.yml)

Callouts:

> [!NOTE]
> Informational aside.

> [!TIP]
> Practical shortcut.

> [!WARNING]
> Something that can go wrong.

Code blocks — always specify the language: ```csharp, ```bash, ```text

File placement

Quadrant	Directory	Example filename
Tutorial	docs/site/articles/tutorials/	07-stateful-testing.md
How-to	docs/site/articles/how-to/	reproduce-a-failure.md
Reference	docs/site/articles/reference/	settings.md
Explanation	docs/site/articles/explanation/	shrinking.md

The how-to/, reference/, and explanation/ directories may not exist yet — create them as needed.

Step 4: Update toc.yml

Every new file must be wired into the nearest toc.yml. Also update docs/site/toc.yml and docs/site/articles/toc.yml if a new section directory was created.

toc.yml format:

items:
  - name: Display Name
    href: filename.md

For a new directory, add a section entry in the parent toc:

  - name: How-to Guides
    href: how-to/toc.yml

And create how-to/toc.yml:

items:
  - name: First guide title
    href: first-guide.md

Step 5: Reorganization (when requested)

When the user asks to reorganize existing docs into Diataxis shape:

1. Map each existing file to its correct quadrant (tutorials stay tutorials; guides/ files map to how-to; some articles may be explanation; configuration/settings/API pages are reference)
2. Propose the new structure as a file tree — show moves, new files needed, files that need splitting
3. Get confirmation before moving files
4. Move files, update all internal cross-references, and rewrite all affected toc.yml files
5. Note: API reference generated by DocFX (api/) is not touched — it comes from XML docs in source

Quality checklist

Before finishing, verify:

• The doc stays in its quadrant (tutorials don't explain theory; reference doesn't teach)
• All code examples compile (mentally verify against the public API)
• Framework tab groups are complete (all four adapters shown where relevant)
• toc.yml updated
• No dead internal links