write-good-docs

Original：🇺🇸 English

Translated

Write, review, and restructure useful documentation with Diataxis, audience-specific README patterns, and AI-writing trope cleanup. Use when creating docs, improving READMEs, reorganizing documentation, or editing prose for clarity.

5installs

Sourcemiguelspizza/skills

Added on2026-06-02

NPX Install

npx skill4agent add miguelspizza/skills write-good-docs

SKILL.md Content

View Translation Comparison →

Write Good Docs

Use this skill when documentation needs to become more useful, not merely longer.

Layout

```
references/diataxis/
```
contains the Diataxis framework reference for classifying documentation into tutorials, how-to guides, reference, and explanation.
```
references/crafting-effective-readmes/
```
contains README templates, checklists, and style guidance.
```
references/ai-writing-tropes/
```
contains prose cleanup guidance for removing common AI-generated writing tells.

Reading Order

Do not read the whole skill directory by default.

Classify the documentation task.
Load only the relevant reference area below.
Write or edit the docs.
Run the AI-writing trope check before finalizing prose.

Task Router

Writing or reorganizing documentation

Start with Diataxis:

```
references/diataxis/compass.md
```

references/diataxis/how-to-use-diataxis.md

Then read the page-type reference that matches the job:

Tutorials:
```
references/diataxis/tutorials.md
```
How-to guides:
```
references/diataxis/how-to-guides.md
```
Reference:
```
references/diataxis/reference.md
```
Explanation:
```
references/diataxis/explanation.md
```

Use the boundary references when content is mixed:

```
references/diataxis/tutorials-how-to.md
```

references/diataxis/reference-explanation.md

references/diataxis/complex-hierarchies.md

Creating or improving a README

Read:

references/crafting-effective-readmes/SKILL.md

references/crafting-effective-readmes/section-checklist.md

references/crafting-effective-readmes/style-guide.md

Choose the template that matches the audience:

Open source:

references/crafting-effective-readmes/templates/oss.md

Internal:

references/crafting-effective-readmes/templates/internal.md

Personal:

references/crafting-effective-readmes/templates/personal.md

Config:

references/crafting-effective-readmes/templates/xdg-config.md

Editing prose that sounds machine-generated