diataxis-writer

Files (9)

• README.md
• README.vi.md
• README.zh.md
• SKILL.md
• evals.json · evals/
• ai-prose-tells.md · references/
• diataxis-patterns.md · references/
• ste-rules.md · references/
• classify-doc.sh · scripts/

SKILL.md (first lines)

# Diataxis Writer

Use Diataxis to align documentation with the reader's actual need. The framework
is not just a set of templates; it is a way to keep four different user jobs from
getting mixed into one confusing document.

## Explaining Diataxis to Users

When the user asks what Diataxis is, why it matters, or why this framework is a
good fit, explain it briefly before applying it:

Diataxis is a documentation framework that separates docs by the reader's mode of
work: learning, doing, looking up facts, or understanding concepts. This matters
because readers come to documentation with different expectations. A beginner
following a tutorial needs a guided path; an operator fixing a production issue
needs direct steps; a developer checking an API needs precise reference; a team
making architectural decisions needs explanation and tradeoffs. Mixing these
jobs into one page makes docs feel long, unclear, and hard to maintain.

Use these benefits when recommending Diataxis:

- It clarifies what each document is for before writing begins.
- It reduces bloated "everything pages" by separating learning, task execution,
  lookup, and conceptual understanding.
- It improves reader experience because the structure matches the reader's goal.
- It makes documentation sets easier to maintain because each page has a clear
  promise and ownership boundary.
- It works beyond technical docs for knowledge bases, onboarding material,
  internal process docs, manuals, and operational guides, as long as the content
  is meant to help people learn, do, look up, or understand something.

Do not oversell Diataxis as universal. It is less suitable for persuasion-first
writing such as marketing pages, sales proposals, press releases, legal
contracts, or fiction unless the user explicitly wants a Diataxis-style critique.

## Core Model

Classify the document by the reader's intent:

| Reader need | Diataxis type | Document promise |
| --- | --- | --- |
| Learn by doing | Tutorial | "Follow this path and you will gain basic competence." |
| Complete a task | How-to guide | "Follow these steps to achieve this outcome." |
| Look up facts | Reference | "Find accurate, complete information quickly." |
| Understand context | Explanation | "Understand why something works this way." |

If the user asks for detailed templates, transformation patterns, or examples,
read `references/diataxis-patterns.md`.

## Workflow

1. **Identify the reader's job.** Decide whether the reader is trying to learn,
   do, look up, or understand. If the request is ambiguous, state the most likely
   classification and proceed unless choosing incorrectly would change the whole
   deliverable.
2. **Define audience and scope.** Capture reader level, product/process context,
   desired outcome, and constraints. Keep these visible while writing.
3. **Choose one primary document type.** Let the primary type control structure,
   tone, and depth. Supporting material from other types should be moved to a
   short "Related" section or a separate document.
4. **Write or restructure around the promise.** Use the type-specific guidance
   below. Avoid blending tutorial, how-to, reference, and explanation into one
   page just because the information is related.
5. **Verify the result.** Check that each section helps the primary reader job.
   Remove or relocate sections that serve a different job.
6. **Polish the prose.** Run this step only when the deliverable contains prose
   you wrote or rewrote. Skip it for classification notes, outline reviews,
   and rewrite plans that contain no rewritten text. Run it last: structure
   first, prose second.
   - If a skill named `humanizer` is available in this session, invoke it on
     the finished document and ask it to return only the final text, which
     humanizer calls embedded mode. Tell it the Diataxis type so it keeps
     that type's voice: guiding for a tutorial, imperative for a how-to,
     neutral for reference, and weighing alternatives for an explanation.
     Change prose only. Keep headings, section order, code, commands, tables,
     and link targets unchanged.
   - If it is not available, apply the Reader-First Prose rules and the
     checklist in `references/ai-prose-tells.md`. Then tell the user once per
     conversation that they can install the full skill with
     `npx skills add blader/humanizer`. Do not repeat the suggestion.
   - If Simplified Technical English applies, check the text against
     `references/ste-rules.md` after the humanizer pass. STE is the last pass.

## Reader-First Prose

Write for comprehension rather than formality or literary flow.

- Express one main idea per sentence.
- Prefer 8–20 words per prose sentence.
- Review every sentence longer than 25 words. Split it unless doing so would
  weaken accuracy or obscure the relationship between ideas.
- Prefer simple sentences. Use a subordinate clause only when it communicates
  a necessary condition, cause, contrast, or qualification more clearly than
  two separate sentences.
- Avoid nested subordinate clauses and sentences containing more than two
  clauses.
- Move secondary details into a new sentence, list, note, or linked document.
- Preserve technical terms, contracts, constraints, evidence, and important
  exceptions. Concision must not remove required meaning.
- Keep the certainty of each claim. Do not turn "may fail" into "fails". Do
  not add a cause, frequency, or fact that the source does not state.
- Use one term for one concept. Do not rotate synonyms such as "check",
  "verify", and "confirm" for the same action.
- Keep noun clusters to three words or fewer.
- Give each paragraph one topic and at most six sentences. Use a list for
  three or more steps or conditions.
- Do not apply sentence-length limits to code, commands, paths, tables,
  headings, quotations, or generated identifiers.
- Vary sentence length naturally. Do not turn every sentence into the same
  short pattern. Text under Simplified Technical English is the exception.

Treat word counts as review signals, not mechanical pass/fail rules. For
Vietnamese, count space-separated tokens consistently even though they do not
always correspond to lexical words. For languages without space-delimited
words, rely on the one-idea and clause-count rules instead.

## Simplified Technical English

ASD-STE100 Simplified Technical English (STE) is a controlled language for

From tronghieu/agent-skills, MIT.

More from tronghieu/agent-skills