diataxis-writer

Name: diataxis-writer
Author: tronghieu

37stars20forks

How to install diataxis-writer?

tronghieu/agent-skills/diataxis-writer

$npx -y skills add tronghieu/agent-skills --skill diataxis-writer

Installs into the current project.

Summary

Write, restructure, classify, and review documentation using the Diataxis framework. Use this skill whenever the user asks to create, improve, audit, or reorganize docs, documentation, knowledge bases, help centers, onboarding guides, internal process docs, manuals, runbooks, pro

Files · 1

View on GitHub

SKILL.md

1	# Diataxis Writer
2
3	Use Diataxis to align documentation with the reader's actual need. The framework
4	is not just a set of templates; it is a way to keep four different user jobs from
5	getting mixed into one confusing document.
6
7	## Explaining Diataxis to Users
8
9	When the user asks what Diataxis is, why it matters, or why this framework is a
10	good fit, explain it briefly before applying it:
11
12	Diataxis is a documentation framework that separates docs by the reader's mode of
13	work: learning, doing, looking up facts, or understanding concepts. This matters
14	because readers come to documentation with different expectations. A beginner
15	following a tutorial needs a guided path; an operator fixing a production issue
16	needs direct steps; a developer checking an API needs precise reference; a team
17	making architectural decisions needs explanation and tradeoffs. Mixing these
18	jobs into one page makes docs feel long, unclear, and hard to maintain.
19
20	Use these benefits when recommending Diataxis:
21
22	- It clarifies what each document is for before writing begins.
23	- It reduces bloated "everything pages" by separating learning, task execution,
24	lookup, and conceptual understanding.
25	- It improves reader experience because the structure matches the reader's goal.
26	- It makes documentation sets easier to maintain because each page has a clear
27	promise and ownership boundary.
28	- It works beyond technical docs for knowledge bases, onboarding material,
29	internal process docs, manuals, and operational guides, as long as the content
30	is meant to help people learn, do, look up, or understand something.
31
32	Do not oversell Diataxis as universal. It is less suitable for persuasion-first
33	writing such as marketing pages, sales proposals, press releases, legal
34	contracts, or fiction unless the user explicitly wants a Diataxis-style critique.
35
36	## Core Model
37
38	Classify the document by the reader's intent:
39
40	\| Reader need \| Diataxis type \| Document promise \|
41	\| --- \| --- \| --- \|
42	\| Learn by doing \| Tutorial \| "Follow this path and you will gain basic competence." \|
43	\| Complete a task \| How-to guide \| "Follow these steps to achieve this outcome." \|
44	\| Look up facts \| Reference \| "Find accurate, complete information quickly." \|
45	\| Understand context \| Explanation \| "Understand why something works this way." \|
46
47	If the user asks for detailed templates, transformation patterns, or examples,
48	read `references/diataxis-patterns.md`.
49
50	## Workflow
51
52	1. Identify the reader's job. Decide whether the reader is trying to learn,
53	do, look up, or understand. If the request is ambiguous, state the most likely
54	classification and proceed unless choosing incorrectly would change the whole
55	deliverable.
56	2. Define audience and scope. Capture reader level, product/process context,
57	desired outcome, and constraints. Keep these visible while writing.
58	3. Choose one primary document type. Let the primary type control structure,
59	tone, and depth. Supporting material from other types should be moved to a
60	short "Related" section or a separate document.
61	4. Write or restructure around the promise. Use the type-specific guidance
62	below. Avoid blending tutorial, how-to, reference, and explanation into one
63	page just because the information is related.
64	5. Verify the result. Check that each section helps the primary reader job.
65	Remove or relocate sections that serve a different job.
66
67	## Type Guidance
68
69	### Tutorial
70
71	Use a tutorial when the reader needs a guided learning experience.
72
73	- Give the reader a safe, repeatable path from zero to a concrete result.
74	- Prefer one reliable route over a catalog of options.
75	- Include enough explanation to keep the learner oriented, but do not interrupt
76	the lesson with deep theory or exhaustive reference material.
77	- Make success visible with checkpoints, expected outputs, and recovery notes.
78	- Avoid assuming the reader can make expert decisions before the lesson teaches
79	the relevant concepts.
80
81	### How-to Guide
82
83	Use a how-to guide when the reader already has context and wants a task done.
84
85	- Start with the outcome, prerequisites, and when to use the guide.
86	- Write action-oriented steps in the order the user should perform them.
87	- Include d

People who liked this also viewed

6 picks

Type

diataxis-writer

37stars20forks

View on GitHub

How to install diataxis-writer?

tronghieu/agent-skills/diataxis-writer

$npx -y skills add tronghieu/agent-skills --skill diataxis-writer

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Diataxis Writer
2
3	Use Diataxis to align documentation with the reader's actual need. The framework
4	is not just a set of templates; it is a way to keep four different user jobs from
5	getting mixed into one confusing document.
6
7	## Explaining Diataxis to Users
8
9	When the user asks what Diataxis is, why it matters, or why this framework is a
10	good fit, explain it briefly before applying it:
11
12	Diataxis is a documentation framework that separates docs by the reader's mode of
13	work: learning, doing, looking up facts, or understanding concepts. This matters
14	because readers come to documentation with different expectations. A beginner
15	following a tutorial needs a guided path; an operator fixing a production issue
16	needs direct steps; a developer checking an API needs precise reference; a team
17	making architectural decisions needs explanation and tradeoffs. Mixing these
18	jobs into one page makes docs feel long, unclear, and hard to maintain.
19
20	Use these benefits when recommending Diataxis:
21
22	- It clarifies what each document is for before writing begins.
23	- It reduces bloated "everything pages" by separating learning, task execution,
24	lookup, and conceptual understanding.
25	- It improves reader experience because the structure matches the reader's goal.
26	- It makes documentation sets easier to maintain because each page has a clear
27	promise and ownership boundary.
28	- It works beyond technical docs for knowledge bases, onboarding material,
29	internal process docs, manuals, and operational guides, as long as the content
30	is meant to help people learn, do, look up, or understand something.
31
32	Do not oversell Diataxis as universal. It is less suitable for persuasion-first
33	writing such as marketing pages, sales proposals, press releases, legal
34	contracts, or fiction unless the user explicitly wants a Diataxis-style critique.
35
36	## Core Model
37
38	Classify the document by the reader's intent:
39
40	\| Reader need \| Diataxis type \| Document promise \|
41	\| --- \| --- \| --- \|
42	\| Learn by doing \| Tutorial \| "Follow this path and you will gain basic competence." \|
43	\| Complete a task \| How-to guide \| "Follow these steps to achieve this outcome." \|
44	\| Look up facts \| Reference \| "Find accurate, complete information quickly." \|
45	\| Understand context \| Explanation \| "Understand why something works this way." \|
46
47	If the user asks for detailed templates, transformation patterns, or examples,
48	read `references/diataxis-patterns.md`.
49
50	## Workflow
51
52	1. Identify the reader's job. Decide whether the reader is trying to learn,
53	do, look up, or understand. If the request is ambiguous, state the most likely
54	classification and proceed unless choosing incorrectly would change the whole
55	deliverable.
56	2. Define audience and scope. Capture reader level, product/process context,
57	desired outcome, and constraints. Keep these visible while writing.
58	3. Choose one primary document type. Let the primary type control structure,
59	tone, and depth. Supporting material from other types should be moved to a
60	short "Related" section or a separate document.
61	4. Write or restructure around the promise. Use the type-specific guidance
62	below. Avoid blending tutorial, how-to, reference, and explanation into one
63	page just because the information is related.
64	5. Verify the result. Check that each section helps the primary reader job.
65	Remove or relocate sections that serve a different job.
66
67	## Type Guidance
68
69	### Tutorial
70
71	Use a tutorial when the reader needs a guided learning experience.
72
73	- Give the reader a safe, repeatable path from zero to a concrete result.
74	- Prefer one reliable route over a catalog of options.
75	- Include enough explanation to keep the learner oriented, but do not interrupt
76	the lesson with deep theory or exhaustive reference material.
77	- Make success visible with checkpoints, expected outputs, and recovery notes.
78	- Avoid assuming the reader can make expert decisions before the lesson teaches
79	the relevant concepts.
80
81	### How-to Guide
82
83	Use a how-to guide when the reader already has context and wants a task done.
84
85	- Start with the outcome, prerequisites, and when to use the guide.
86	- Write action-oriented steps in the order the user should perform them.
87	- Include d

People who liked this also viewed

6 picks

Type