Of Writing Development

Writing Like an Engineer, Not a Novelist

I spent three years trying to build a team-wide standard for technical writing across our engineering org. We went through two full rebrands of the documentation process, hired a copywriter who didn't understand semver, and ended up with something that actually worked. It was ugly for most of the way there. The core idea behind Of Writing Development is deceptively simple: treat the act of writing as a first-class engineering activity, not an afterthought you squeeze in between feature work. Most teams write documentation whenever they remember. That always means never. The practice flips that by embedding writing tasks directly into the development pipeline — commit messages that document decisions, PR descriptions that read like mini RFCs, and README files that are versioned alongside the code they describe.

Getting Started With Of Writing Development

Start with commit messages. I know this sounds trivial but it is where everything breaks or holds together. Your standard git log output is a minefield of useless entries like "fix stuff" and "wip." Of Writing Development demands that every commit follows a structured format: a one-line summary that states what changed and why, followed by a blank line and then a short paragraph explaining the reasoning. Not what you did — why you did it. Someone reading this six months from now will care about the why. Here is the concrete format I use and recommend: Type: scope — one line describing the change. Then a blank line. Then 2-4 sentences on the motivation. Type is one of: feat, fix, refactor, docs, test, chore. Scope is the module or subsystem. The body explains the reasoning. That is it. Nothing fancy.

Next you build a pull request template. Not the default GitHub template that asks "Did you test this?" Everyone tested this or they would not have pushed it. Your template should ask three questions: what problem does this solve, what trade-offs were considered, and what edge cases remain unhandled. Two of those three questions force you to think before you submit. The third question catches the stuff that usually gets lost. I ran into a real problem with this approach about eight months in. Our junior developers started filling out PR templates like they were tax forms — every field populated with vague, unverifiable statements. "Trade-offs considered: performance vs readability." That is not a trade-off analysis. That is a shrug in sentence form. The workaround was to add required fields that pulled in context from existing issues and design docs. You could not submit a PR without linking to at least one related ticket or spec. It forced specificity. It also slowed down PR throughput by roughly 20 percent initially, which pissed off the PM team. We adjusted by auto-filling template sections from issue metadata so the friction dropped after a couple weeks.

Documentation as Versioned Artifacts

The part most teams skip is treating README and API docs as versioned artifacts under source control. If your documentation lives in a separate wiki or a Confluence space that nobody links to from the actual codebase, you already lost. The documentation drifts. It becomes fiction. Of Writing Development requires that any file a developer reads to understand how to use or extend the code lives inside the repository alongside that code. This creates a versioning problem. Your API changes in v2.3 but the README still describes v1.8 behavior because nobody updated it. The fix is simple and unpleasant: pin documentation versions to release tags and keep them in subdirectories. docs/v1/, docs/v2/, and so on. When you release, the previous version's docs stay correct. The next version's docs get updated during development, not after. This adds about 15 minutes of overhead per release cycle. It saves approximately 40 hours per quarter in support tickets and confused Slack messages. There is a counter-intuitive insight here that nobody tells beginners: the best documentation is not comprehensive documentation. It is narrowly scoped, clearly versioned documentation that tells you exactly what you need to know for your current task and nothing more. Comprehensive docs are always incomplete because comprehensiveness is impossible to maintain. Scoped docs are maintainable because they are small enough to keep accurate.

The Downsides Nobody Talks About

Of Writing Development does not work for every team and it will fail in specific scenarios. If your team ships multiple times per day with small hotfixes, the commit message overhead becomes a real drag. You will spend more time writing good messages than writing code. In that case, batch your documentation practice. Focus on PR templates and versioned docs, but relax the commit message standard for minor fixes. The second failure mode is when the team lacks domain expertise. Writing well requires understanding. If your developers cannot explain why a decision was made because they were not involved in the original problem, they will write vague commit messages and hollow PR descriptions. No template in the world fixes that. The solution is pair programming on design decisions before the code gets written. Force the writing to happen during the design phase, not after implementation. A third limitation is tooling resistance. Some platforms do not support structured commit messages well. Legacy CI/CD pipelines may parse commit logs and break if you change the format. I spent two days fixing a Jenkins job that choked on the em dash in a commit type prefix. Use hyphens instead of fancy punctuation. Keep it simple.

Measuring Whether It Is Working

You can tell Of Writing Development is taking hold when a new team member can trace a bug back to the commit that introduced it by reading the commit message alone. You can tell it is failing when the same person has to read 30 commits across three branches to understand why a feature exists. Track three metrics: average lines in a PR description body, number of unresolved edge cases raised during review, and the frequency of "this doesn't match the docs" support requests. The first two should improve within a month. The third takes longer — usually 4-6 months — because documentation versioning catches up slowly. If your metrics are not moving after two months, the problem is likely enforcement, not methodology. Require the practices in code review. Reject PRs with shallow descriptions. Reject merges with undocumented breaking changes. This is the part that makes people uncomfortable because it slows things down. Good. It should slow things down. Speed without precision is just faster garbage production.

A Word on Tools

You do not need special tools for Of Writing Development. Git, your issue tracker, and your platform's PR template system are enough. Pre-commit hooks can enforce message format if you want automation. Husky works on Node projects. pre-commit.io works everywhere. Set the hook to reject commits that do not match your pattern and you eliminate the consistency problem entirely. The tool I found most useful was a simple script that parsed the last 50 commits and generated a changelog-style summary. It caught patterns where we were repeating the same fix across multiple branches without realizing it. That saved us from a duplicate bug that would have landed in production on a Friday. That is the whole thing. Structure your writing the same way you structure your code. Version your docs. Enforce standards through review, not hope. And accept that it will feel slower at first. It is supposed to.