When I started my Git and GitHub for Technical Writers series, I had a plan. The content would be accurate, the structure sound, and the logic clean. I would write each part, host it on a GitHub repo, and use LinkedIn to drive the traffic.
The content was accurate. The structure was technically sound. And yet something was wrong. A reader landing on Part 3 had to orient themselves before they could learn anything. The information was there. The experience of moving through it was friction, not flow.
That was not a writing problem. I had not written a single bad sentence. It was a system problem.
The real job of a technical writer is not writing. It is designing how information works.
The symptom nobody names correctly
At some point, every documentation team hits the same wall. The guides are well-written. The grammar is clean. The tone is consistent. And yet users still can’t find what they need. Engineers still get the same questions in Slack. Onboarding still takes longer than it should.
The instinct is to write more. Add more detail. Create more guides. But that’s not the problem. The problem is that nobody designed how the documentation works, only what it says.
What a system problem looks like in practice
You’ve seen this before, even if you didn’t have a name for it. Guides that contradict each other because two writers worked in isolation. Installation docs missing a step that everyone on the team knows but nobody wrote down. A getting-started page referencing a feature deprecated eight months ago, with no named owner to fix it. Content scattered across Notion, Confluence, a GitHub wiki, and a PDF someone emailed in 2022.
None of that is a writing failure. Every individual document might be perfectly written. It’s a system failure. Academics call it Information Architecture. I call it Documentation Entropy: the slow, compounding drift that happens when documentation is written but never designed as a system. Every page that becomes stale, every link that breaks, every step that goes missing is entropy accumulating. A writer who can only fix sentences cannot fix it. A writer who can only fix sentences can’t fix it.
What the process revealed
The solution was not to rewrite the content. It was to change the infrastructure: host it as a live static site where a reader could move through six parts the way you move through a story, with direction, with context, with a sense of where they are and where they are going.
Rebuilding the infrastructure also became content in itself. Documenting the process gave my audience something no amount of accurate writing could: a window into how documentation decisions actually get made. I was not just thinking about whether the information was correct. I was thinking about how a reader moves through it.
That is the shift. From writing to systems thinking.
The difference between writing and systems thinking
Writing asks: is this clear? Is this accurate? Is this readable?
Documentation systems ask: where does this live? Who owns it? How does it get updated when the product changes? Can any part of it be reused? What happens to it at scale?
One is about the quality of a document. The other is about the health of an entire information architecture. Most writers are trained for the first. Most product teams desperately need the second.
The same content. Two completely different levels of thinking.
Take an installation guide. A writing-focused approach produces clear, accurate, well-formatted steps. A systems-focused approach asks different questions before a single word is written: Should prerequisites be a separate reusable section or embedded in this guide? How does this guide connect to the configuration guide that follows it? What’s the versioning strategy when v2 ships? Who is the subject matter expert and what’s the review cadence?
The output might look similar on the surface. But the second approach produces documentation that survives the product, and the team, changing around it. That’s the difference between documentation that works on launch day and documentation that still works two years later.
One of a technical writer’s core jobs
Architecture in technical writing is building doors that connect documents: foreseeing how your audience moves, and making sure they never feel lost in the middle of it. A reader who stumbles onto Part 3 of a series without reading Part 1 must find something within that document telling them it’s part of a whole. Every piece carries its own weight and solves a specific problem, but it also has to signal its place in something larger.
That’s not a formatting decision. It’s a systems decision. Your job is to make complexity followable, the way a story feels native to the world of whoever is reading it.
Why this matters more now than it ever has
Modern product teams move fast. Features ship in weeks. APIs change. Products pivot. In that environment, documentation that isn’t designed as a system becomes a liability almost immediately. It goes stale. It fragments. It contradicts itself. The cost of fixing it compounds every sprint.
Teams that understand this aren’t just looking for writers. They’re looking for people who can think about information architecture, work alongside engineers in Git-based workflows, own content strategy across a product, and make decisions about structure and reuse that a product manager doesn’t have the context to make.
Where this series is going
That is the opening argument. Part 02 makes it concrete. Most documentation is built like a bakery: one product, one shelf, accurate and useful but isolated. A reader arrives, finds what they need or doesn’t, and leaves. There is nothing to pull them deeper.
Building a supermarket is a different job entirely. That is what Part 02 is about.
Next time you’re asked to fix a typo, pause for one second and ask yourself: does this error exist in five other places?
If yes, you don’t have a typo problem. You have a system problem. A systems thinker does not fix the five instances. They find the source — the template, the shared component, the unowned page — and fix it once.
The system always tells you what it needs
The shift from writing to systems thinking rarely happens in planning. It happens in the work itself; when a broken link reveals a connectivity failure, when a stale page reveals an ownership gap, when a support ticket reveals a findability problem that no amount of careful writing could have prevented.
The system always tells you what it needs. The question is whether you are looking at the sentences or at the structure.
Already thinking about the tooling layer? My Git & GitHub for Technical Writers series covers the Git-based workflows that modern documentation systems run on.
Discussion