Review software guides with AI
Review a software guide paragraph by paragraph and identify where its purpose changes between doing, learning, looking up and understanding.
Review software guides with AI when something about a draft feels difficult to use even though the facts are accurate. A configuration reference that suddenly asks the reader to complete a long exercise has changed purpose halfway through. The writing-documentation-with-diataxis skill helps locate the passage and describe the mismatch.
Use the guide's two questions as a compass: is the reader acting or thinking, and are they acquiring a skill or applying existing knowledge? Those answers point towards a tutorial, how-to, reference or explanation. You can revise a single awkward paragraph before deciding whether a larger restructure is warranted.
What it does
- Find background material that interrupts a procedure.
- Test whether a tutorial offers one coherent learning route.
- Review the consistency of a software reference entry.
- Separate a useful conceptual explanation from instructions that belong elsewhere.
- Suggest a targeted rewrite and explain the reader problem it solves.
Install and use
- Give the agent the passage, its intended reader and the task or question. The skill uses written references and needs no separate program.
- Ask for the specific point where the reader's need and the draft's purpose diverge.
- Review a proposed revision against the original scenario, then decide whether any neighbouring pages also need attention.
FAQ
Source
Made by Sam McLeod (sammcj). Original skill: writing-documentation-with-diataxis, published on GitHub under the Apache-2.0 licence.
View on GitHub