Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing.
91
87%
Does it follow best practices?
Impact
96%
1.11xAverage score across 5 eval scenarios
Passed
No known issues
{
"context": "Tests whether the agent follows tutorial-specific Diátaxis patterns: verb-led title, Goal→Prerequisites→Numbered steps→Verifiable result→Final outcome structure, minimising explanation in favour of doing, and ensuring every step produces a visible testable result.",
"type": "weighted_checklist",
"checklist": [
{
"name": "Verb-led title",
"description": "The document title starts with an imperative verb (e.g., 'Build', 'Create', 'Set up', 'Write', 'Run') rather than a noun or 'How to'",
"max_score": 10
},
{
"name": "Goal statement present",
"description": "The document opens with an explicit goal statement telling the reader what they will have achieved by the end (e.g., 'By the end of this tutorial, you will have...')",
"max_score": 10
},
{
"name": "Prerequisites section",
"description": "A prerequisites or 'Before you begin' section is present before the first step",
"max_score": 8
},
{
"name": "Numbered steps",
"description": "The main body of the tutorial uses a numbered list (ordered list) for the procedural steps",
"max_score": 8
},
{
"name": "Verifiable result per step",
"description": "At least 3 individual steps include an explicit expected output or verification check the reader can perform (e.g., showing expected terminal output, telling the reader what they should see)",
"max_score": 12
},
{
"name": "Final outcome stated",
"description": "The document ends with a clear final outcome or summary of what has been accomplished",
"max_score": 8
},
{
"name": "Minimises explanation",
"description": "The document does NOT contain long conceptual paragraphs explaining why things work the way they do — explanation is limited to one sentence or less per step",
"max_score": 10
},
{
"name": "Maximises doing",
"description": "The majority of the document consists of actions to perform (commands to run, files to create) rather than prose descriptions",
"max_score": 10
},
{
"name": "Beginner self-sufficiency",
"description": "The tutorial does NOT reference external resources or documentation that a beginner would need to consult in order to complete any step",
"max_score": 8
},
{
"name": "No reference table mixing",
"description": "The document does NOT include a table of all options, flags, or parameters (reference material) mixed into the tutorial body",
"max_score": 8
},
{
"name": "No conceptual digressions",
"description": "The document does NOT include a section explaining background concepts (e.g., 'How tokenisation works', 'Understanding stdin/stdout') that is not directly needed to complete the steps",
"max_score": 8
}
]
}