Approach · shipping · in production
Document While Shipping
This approach integrates documentation updates directly into the code commit process, ensuring that documentation always reflects the current state of the system.
Document While Shipping is the practice of embedding documentation updates directly into the development workflow, ensuring that every code change is accompanied by its corresponding documentation update within the same commit.
What it is
This means that when I modify a piece of code, the relevant documentation — whether it's a `README.md` for a service, an API specification, or an internal process guide — is updated in the same Git commit. The documentation is treated as code: it's version-controlled, part of the pull request, and subject to the same review process. It's not about writing extensive documentation from scratch with every change, but rather maintaining the accuracy and currency of existing system knowledge.
Why I do it this way
I learned the hard way that stale documentation is often worse than no documentation at all. It misleads, wastes time, and erodes trust in the system's internal knowledge base. Separating documentation tasks into future sprints or dedicated 'tech debt' work almost guarantees they will be deprioritized and never completed. By integrating documentation into the immediate shipping process, it becomes a non-negotiable part of the work. For a solo operator running a multi-product studio with AI as the team, this discipline is critical for maintaining a clear, accurate understanding of complex systems like the backend for Total Formula 1 or the agent orchestration for Inky. When I instruct Claude Code as the Engineer to generate or modify code, I also prompt it to update relevant documentation, which streamlines this process significantly.
How it works in practice
When I make a change — for instance, adding a new webhook handler for Stripe payments in a Firebase function, or modifying a user onboarding flow for Pregnancy Power Hour — the commit includes the code changes, the updated Firebase function, and an update to the `PAYMENT_FLOWS.md` or `USER_FLOWS.md` document. This update clarifies the new handler's purpose, expected inputs, and outputs. If it's a new feature, a high-level overview might also go into a project-level `SUMMARY.md`. This is often facilitated by my Agent-First Development approach, where agents are trained to recognize when documentation updates are necessary based on code changes and propose them in the same PR. I review the proposed documentation alongside the code, ensuring consistency and clarity. This also ties into Tests as Design, where robust tests provide executable specifications, but human-readable prose is still necessary for context and high-level architectural understanding.
Where this breaks down
This approach isn't a substitute for upfront design documentation for major architectural shifts; those still require dedicated planning documents first. It can also feel like an overhead for truly trivial changes, though I find the discipline of even a minor doc update beneficial. The initial friction of consistently updating documentation can slow down individual commits if the documentation impact is significant and unanticipated. However, this friction often serves as a useful signal that the change might be more complex than initially perceived, prompting a deeper review before shipping. Maintaining consistency across a growing number of small, updated documents can also become a cognitive load if file structures and naming conventions aren't rigorously applied.
FAQs
- Isn't this too much overhead for small changes?
- The overhead is minimal when it's a habit. The cost of stale documentation, which I've learned the hard way, far outweighs the few extra minutes per commit. It's an investment in future clarity.
- How do you handle documentation for complex new features?
- Major features typically start with a preliminary design document. 'Document While Shipping' then applies to keeping that design document and all related system documentation current as the implementation progresses incrementally.
- Does this replace other forms of documentation?
- No. It ensures existing documentation stays fresh and accurate. Architectural overviews, user guides, and detailed API references still exist, but they are continuously updated rather than becoming outdated.
I run this and four other brands. Want to see the operator playbook in detail?
Get the Builder's Playbook →