| 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:
- The relevant existing doc files in
docs/site/articles/ — understand what's already there
- The applicable
toc.yml — know where the new file fits
- The source code for the feature being documented — read the public API surface (
PublicAPI.Unshipped.txt and the relevant .cs files)
- 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:
- 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)
- Propose the new structure as a file tree — show moves, new files needed, files that need splitting
- Get confirmation before moving files
- Move files, update all internal cross-references, and rewrite all affected toc.yml files
- Note: API reference generated by DocFX (
api/) is not touched — it comes from XML docs in source
Quality checklist
Before finishing, verify:
