All products

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

  1. Give the agent the passage, its intended reader and the task or question. The skill uses written references and needs no separate program.
  2. Ask for the specific point where the reader's need and the draft's purpose diverge.
  3. 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