Documentation

Code explains what the system does and how it does it. Documentation explains why.

Docs as Code

Developer documentation at WordLoop is treated with the same reverence as the production source code.

• Colocation: The documentation lives in the same Git Monorepo (services/wordloop-docs) as the code itself.
• Atomic Commits: When an engineer introduces a breaking change to an API or modifies an architectural boundary, the Pull Request must simultaneously include the updates to the documentation. A PR without the accompanying doc updates is an incomplete PR.

Technical Maintenance

Having no documentation is dangerous; having out-of-date documentation is catastrophic.

• Stale guides erode developer trust. Once trust in the documentation is lost, engineers resort to manual code archeology, which destroys velocity.
• We invest in generating documentation programmatically wherever possible. Our API Reference is generated directly from OpenAPI specs derived from code annotations.
• The WordLoop documentation site is automatically built and tested in our CI pipeline to ensure links are valid and syntax is correct before deployment.

Tone and Writing Style

How we write technical documentation is just as important as what we write.

• Grounded and Matter of Fact: Avoid sensationalism, buzzwords, or heavily referencing specific calendar years or external "trendsetters" that age poorly.
• Domain Agnostic: Keep engineering principles decoupled from our specific product domain (e.g., audio, transcription). Focus on universally applicable software engineering practices.
• Human and Accessible: Write clearly and concisely. We are writing for other human engineers.
• Positive Framing: Lead with the solutions we embrace, rather than anchoring explanations on anti-patterns or practices we avoid. Talk about what we do and why we do it.
• Optimize for AI-Readability: Structure documents with deterministic, semantic headings and concise context chunks. Documentation is increasingly parsed by IDE assistants and RAG pipelines; writing clearly ensures both humans and LLMs can extract accurate answers.
• Progressive Disclosure: Deliver the most critical, actionable information at the top of the document. Defer deep architectural lore or historical context to the latter half of the page so a developer rushing to solve an outage isn't forced to read a novel.
• Focus on the What and Why: Clearly articulate what we believe as an organization, what practices we embrace, and the concrete benefits those practices provide us. Lead with value and clarity.
• Outcomes, Not Principles: When discussing implementation details outside of the ./principles directory, focus strictly on the concrete outcomes of applying our principles. The principles directory should hold the principles themselves; everything else must document the structural or behavioral outcomes of those principles.

Who is Responsible?

Everybody. The concept of a siloed "technical writer" who cleans up after engineers is incompatible with how we build software. The engineer who writes the feature writes the docs.