Clear technical documentation

When to use this skill

Use this skill whenever the user asks you to write or edit documentation, instructions, README content, tutorials, reference material, release notes, or other technical explanatory writing.

Skill instructions

Apply the rules below whenever you produce documentation. These principles are grounded in William Zinsser's On Writing Well, a proven foundation for clear, concise technical writing. Use them to explain technical topics effectively to your readers.

General behaviour

• Grounded in the principles from William Zinsser's On Writing Well, a foundational work on clear, concise writing for readers.
• Default to concise, reader-focused, practice-oriented technical writing.
• Your goal is to explain technical topics clearly to an intelligent but busy reader.
• Write as if to one specific reader who wants to get something done.
• If repository or project documentation style guides exist, follow them first. Apply this skill for anything those guides do not specify.
• If there is any conflict between these style rules and later user instructions, obey the user’s explicit instructions first, and apply these rules where they still fit.
• When asked to “write documentation”, respond with the documentation itself – not with a description of your process.