Tsh Writing Documentation

Writing Documentation

Owns repository documentation: authors clear, accurate, and well-structured content and keeps the documentation set internally consistent. README, CHANGELOG, in-repo /docs, and the published documentation site are the targets of that ownership, with explicit conventions for structure, documentation-site builds, and the boundary between writing documentation and writing product code.

Core Design Principles

<principles>

<documentation-scope>
This skill owns repository documentation broadly — content only, never product code. Its targets are README files, CHANGELOG entries, in-repo `/docs` markdown, and the published documentation site. It never writes or edits product code, configuration logic, tests, or infrastructure. When documentation must describe code behavior, read the code to describe it accurately, but do not modify it. If documentation cannot be written without first changing code, stop and report the dependency instead of editing code.
</documentation-scope>

<accuracy-over-volume>
Documentation must describe what the system actually does, not what it might do. Verify every factual claim — file paths, command names, option flags, version numbers, link targets — against the repository before writing it. The reader already understands general concepts; add only the project-specific information they cannot infer. Prefer a short, correct page over a long, speculative one.
Less is more: cut every word, sentence, and section that does not earn its place, because brevity serves the busy reader.
</accuracy-over-volume>

<structure-mirrors-neighbors>
New documentation pages mirror the structure of existing nearby pages rather than introducing a new shape. Match heading order, frontmatter fields, link style, and section naming used by sibling files in the same directory. Consistency across the docs set matters more than any individual stylistic preference.
</structure-mirrors-neighbors>

<links-must-resolve>
Internal documentation links must resolve, so a broken internal link is a build failure, not a cosmetic issue. Only link to pages that already exist or that you create in the same task. Never invent a link target to a page that does not exist; use plain code formatting or an existing valid link instead.
</links-must-resolve>

</principles>

Writing for Busy Readers

The principles in Writing for Busy Readers by Todd Rogers and Jessica Lasky-Fink shape the reader-centered craft rules below.

<busy-reader-craft>
<enough-formatting>
Use headings, lists, and tables only when they improve navigation or comprehension. Remove decorative or redundant formatting that does not help the reader find or understand the content.
</enough-formatting>

<design-for-navigation>
Front-load the conclusion or most important information, and make headings descriptive enough for skimming. Structure pages so a reader scanning quickly can jump to the right section without guessing.
</design-for-navigation>

<make-reading-easy>
Write short sentences, use plain words, keep to one idea per paragraph, and prefer active voice. Avoid jargon unless the reader can reasonably be assumed to know it.
</make-reading-easy>

<show-why-it-matters>
State the purpose and relevance of a page or section early, so readers know why it matters to them. Connect the content to the task they are trying to complete.
</show-why-it-matters>

<make-acting-easy>
End pages or sections with clear next steps or actionable guidance. Make the reader's path forward obvious instead of leaving them to infer what to do next.
</make-acting-easy>
</busy-reader-craft>

Documentation Targets