What Software Engineering Taught Me About Technical Writing

A few years ago, a software company brought me in to help them figure out why their support queue had exploded. The culprit turned out to be surprisingly mundane: their UI had changed, and nobody had updated the documentation.

Specifically, the documentation explained how customers could claim a military discount, a process that had been straightforward in the old interface and was now buried so deeply in the new one that customers couldn’t find it. The documentation pointed to UI elements that no longer existed where the docs said they would. Support was fielding the same question hundreds of times. Engineers knew the UI had changed. Support knew customers were confused. The documentation team hadn’t been told either of those things.

By updating the UX writing to make the discount more discoverable and rewriting the documentation to reflect the new interface, we reduced support calls by roughly 80%. The fix took a couple of days. The problem had been accumulating for months.

That experience crystallized something I’d been developing instinctively through years of software engineering: documentation and code are not separate disciplines that occasionally need to coordinate. They are the same discipline, and treating them as anything else is how you end up with a support queue full of preventable questions.

Here’s what two decades of software engineering taught me about technical writing that most writers never learn.

Documentation and source code are inseparable

No code should ship without documentation that reflects it. This usually doesn’t mean a full rewrite. Sometimes a changelog entry is enough. But something. The moment code and documentation diverge, you have a documentation problem, and that problem will compound silently until it becomes a support problem.

Most technical writers work downstream of engineering. Code ships, then documentation catches up, then support handles the gap in between. I’ve never been comfortable with that model because I’ve seen what it costs. The military discount situation wasn’t unusual. Instead, it was the predictable outcome of a process that treated documentation as a finishing step rather than an integral one.

The fix isn’t complicated: documentation should be part of the definition of done. Not a nice-to-have. Not a follow-up ticket. Done means the code works, the tests pass, and the documentation reflects the change. Every time.

Technical depth that most writers outsource

Here’s something I’ve noticed about a lot of technical documentation, particularly API documentation: it’s written by people who have read about APIs rather than people who have built with them.

There’s a meaningful difference between understanding how to call an API using cURL and then translating that into working code, versus knowing that OpenAPI exists and can generate a reference document. The generated reference will tell you what the endpoints are, but it won’t tell you why an engineer would choose PUT over PATCH for a particular update operation, what a 429 response code actually means for a client implementation, or why the authentication flow behaves differently than the documentation implies when tokens are near expiration.

I know these things because I’ve spent decades writing code that calls APIs, hits edge cases, reads error responses, and occasionally fails in production in ways that the documentation didn’t warn me about. That experience doesn’t just make me a more accurate technical writer; it makes me a more useful one. I know which questions to ask before a user has to ask them.

Reading the support queue as a documentation audit

The military discount situation taught me something I now treat as a standing rule: the support queue is the most honest documentation audit you will ever get.

Every support ticket represents a question the documentation failed to answer. Not might have failed to answer, just failed. The user looked but didn’t find what they needed, so they reached out to a human being instead. That’s an expensive outcome for the company and a frustrating one for the user, and it happened because somewhere in the documentation, words were missing or wrong or pointed to a UI element that no longer exists.

Engineers rarely read support tickets. Technical writers rarely have access to them. That communication gap, the same one that let the military discount problem fester for months, is endemic to the industry. Bridging it is one of the most valuable things a technical writer with an engineering background can do, because they speak both languages fluently enough to connect the failure in the queue to the gap in the docs.

When I start working with a new client, one of the first things I ask for is access to their support history. The documentation problems are almost always right there, hiding in plain sight.

The communication gap between engineering and support

The military discount problem had three causes: outdated documentation, poor UX writing, and a complete absence of communication between the engineering team that changed the UI and the support team absorbing the consequences.

This is not unusual. In most technology companies, engineering and support exist in almost entirely separate worlds. Engineers ship code. Support handles users. Documentation sits somewhere in between, theoretically serving both, practically accountable to neither.

A technical writer who has worked as a software engineer understands both worlds from the inside. They know how engineering teams think about releases, what gets prioritized and what gets deferred, and why documentation updates are the first thing to fall off the list when a deadline is close. They also understand, viscerally, because they’ve been on the receiving end, what it costs when users can’t find the answer they need.

That dual perspective is what makes the difference between documentation that’s technically accurate and documentation that actually works. Accuracy is the floor. Usefulness is the goal. Getting from one to the other requires understanding not just the product, but also the humans on both sides.

What this means in practice

I didn’t set out to become a technical writer. I set out to build software, and somewhere along the way, I became obsessed with the gap between how well software worked and how poorly it was explained. That obsession eventually became Inkwright, Inc.

The engineering background isn’t a credential I mention to sound impressive. It’s the foundation of everything I do differently. It’s why I insist that documentation be part of the release process, not an afterthought. It’s why I can write API documentation that answers the questions developers actually have, not just the ones that are easy to answer. It’s why I read support queues before I write a single word of new documentation.

Great technical writing isn’t about making complex things sound simple. It’s about understanding complex things deeply enough to explain them accurately, completely, and in the order that actually helps. That requires living in the complexity first.

Two decades of software engineering gave me these insights. Every document we produce at Inkwright, Inc. is built upon this experience.

Inkwright, Inc. provides technical writing and ghostwriting services for technology companies. Get in touch.