TheSoftwareHouse 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
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.
Documentation Targets
| Target | Location | Conventions |
|---|---|---|
| README | repo root README.md and nested README.md files |
Plain Markdown; keep headings and tone consistent with the existing file. |
| CHANGELOG | CHANGELOG.md |
Append entries in the existing format; do not rewrite historical entries. |
| In-repo docs | /docs markdown |
Plain Markdown; follow the structure of neighboring documents. |
| Documentation site | published documentation pages | Markdown documentation pages with standard frontmatter (sidebar_position, title); internal documentation links must resolve. |
Workflow
Use the checklist below and keep it synchronized with your todo list:
Documentation progress:
- [ ] Step 1: Identify the documentation target and audience
- [ ] Step 2: Gather accurate source facts
- [ ] Step 3: Match the neighboring structure
- [ ] Step 4: Write or update the content
- [ ] Step 5: Validate links and the docs build
Step 1: Identify the documentation target and audience. Determine which target type the task touches (README, CHANGELOG, in-repo /docs, or the documentation site), who the reader is, and what they need to accomplish. Confirm the change is documentation-only and not a disguised code change.
Step 2: Gather accurate source facts. Read the relevant code, configuration, and existing documentation to verify every claim you intend to make. Do not document behavior you have not confirmed.
Step 3: Match the neighboring structure. Open one or two sibling pages in the same directory and mirror their frontmatter, heading order, link conventions, and section naming. For the documentation site, reuse the established page shape for that section (agent pages, skill pages, prompt pages).
Step 4: Write or update the content. Write concise, accurate prose. Keep edits scoped to the documentation files named in the task. Do not touch product code, tests, or infrastructure.
When writing prose, apply the reader-centered craft rules in Writing for Busy Readers above.
Step 5: Validate links and the documentation build. For documentation-site changes, run the documentation site build; broken internal links must resolve or the build fails. For README, CHANGELOG, and /docs changes, verify referenced paths and links resolve manually. Fix issues before handing off.
Write vs. Review
This skill writes and updates documentation. It does not perform formal code review or design review. When a documentation change depends on a product-code change, report the dependency to the orchestrator rather than making the code change. When the documentation needs sign-off on technical accuracy beyond what the source files reveal, surface the open question instead of guessing.
Connected Skills
tsh-technical-context-discovering- to confirm project conventions and existing documentation patterns before writing.tsh-codebase-analysing- to read and understand the code or artifacts a documentation page must accurately describe.tsh-creating-instructions- to keep declarative project rules in instruction files rather than narrative documentation.