Things technical writers shouldn't care about... yet
Strategy, Michael Porter wrote, is choosing what not to do. Now, the problem with knowledge work such as the one tech writers carry out is that it’s full of things that seem to require equally important, time-consuming decisions. While engaging in lengthy disquisitions might be alluring, endlessly combing the Zen garden of theory doesn’t solve the basic problem of the docs hierarchy of needs, which is writing the damn docs and making sure they’re accurate and useful.
Given the importance of docs as vital infrastructure, some of our activities risk alienating stakeholders and docs contributors, further imperiling the standing of our role in companies that need to measure our impact and figure out which of the three budgets we’re supporting. We’re not alone in this: software developers and designers also go through similar balancing acts: Shall we park that project to optimize compile time so we can ship the feature earlier? Answer is Yes.
Don’t get me wrong: Many things matter, but not at all times, and not in all situations. Some, though, are almost never important in the way we think, nor hold the urgency we ascribe to them. What follows is a list of the things I believe tech writers are often spending too much time working on and improving. This is not to say that they’re not relevant; my point is that those tasks deserve less attention most of the time. Nothing will break if we don’t do them now.
Docs navigation matters more to writers than to readers
In The best docs are the ones we don’t remember, I defended the concept that the docs experience should be mostly transparent, like crossing a door to get to another room; if we remember docs, it’s usually because something is wrong with them. The same applies to docs navigation: users generally only complain about it when it’s utterly broken. A good navigation system helps methodical readers, though those are few. And some use mobile phones, where the nav is hidden.
Writers often find it hard to believe that nobody looks at their precious four-level navigation tree and that users arrive from direct links shared in chats, in-product help, organic search or, more recently, AI search. It’s the same feeling that book authors must feel when they find out that people usually use the subject index or, when reading ebooks, rely on the search feature instead of orderly crawling through the table of contents. Because navigation is utterly useful… but only for us, the writers.
The most useful aspect of a solid information architecture and the resulting navigation system is that it helps writers write. It also helps writers in communicating with product managers and teams: Yes, we say, we’ll build a cool house and we’ve the perfect plot of land for it. Of course product managers will like this, because it helps align their mental models with ours. They get it, PMs will think. Knowing that we see a feature in a certain way is reassuring for all people involved in building and documenting it.
Alternative priority: Improving search and building a powerful AI-powered agent that leverages docs-as-data. This is the age of conversational search and agentic knowledge. A broken search system will hurt users more than a less-than-ideal navigation sidebar, because asking is easier than exploring.
Beautiful documentation will backfire if docs quality is sub-standard
Who doesn’t like a cool documentation website? I want our docs to look like Stripe’s or Viam’s, say startup founders everywhere. It starts with typography, spacing, perhaps some considerations about inline icons. All reasonable concerns. Before you realize it, though, folks are obsessing over the package, debating kerning, margins, link decorations, callout styles in screenshots, and the ultimate nightmare of all: dark mode. Never mind that we seldom have design resources: we’ll figure something out.
Some of the best docs I know are intensely ugly. Rust docs’ design screams 1996, which perhaps suits system programmers’ taste; they’re also among the best software documentation I’ve ever read. Other docs sites are lucky enough to have great design, but you can be sure they got there because docs were treated as a first class product from the very beginning, as the UI for enablement. They didn’t get there by chance. They did not neglect other priorities to bet it all on clever special effects.
The first priority of documentation is to help onboard users, guide them through complex procedures, and answer their questions should they get stuck. All else is superfluous unless it’s there to serve the UX of the documentation in a meaningful, impactful way. Syntax highlighting in snippets is useful because it lets developers understand at a glance a piece of code. Smooth scroll animations when clicking something in the table of contents, on the other hand, don’t generally solve tangible problems.
What’s more: AI won’t care about your layout when consuming docs. Users with accessibility needs won’t pause to marvel at that beveled call-out. Multichannel content strategies might render most of the web design you’ve so carefully crafted into a waste of resources. As much as we’d like to craft beautiful docs, we also have to be pragmatic about it and not build a house from the roof. If that means postponing those CSS improvements or do them on the side after all else is done, so be it.
Alternative priority: Focus on coverage, accuracy, and freshness first. Prefer function over finish. Use standard solutions for diagrams, like Mermaid. Don’t obsess over pixel perfection. Substance beats beauty all the time, unless you’re in the business of beauty itself. Fast and good is better than nice and slow.
Style guides must be pragmatic, not scholastic nitpicking compendiums
Few artifacts in a tech writer’s arsenal are as prone to bike-shedding as the style guide. It often begins with the noblest of intentions: to create a unified voice and ensure consistency across the docs. We agree on tone, on how to format titles, on how we write our company’s name. So far, so good. But soon, the Great Style Guide Schism of Antioch erupts and you’ve lost an entire afternoon to a Slack thread debating the finer points of en-dashes versus em-dashes.
It’s my belief that a style guide’s purpose is not to be an intellectually satisfying exercise in prescriptive grammar. Its primary job is to reduce cognitive load for both the user and the writer. For the user, its value lies in providing semantic consistency. Knowing that a specific term always refers to the same feature is critical for their understanding. This is the part of the style guide that has a tangible impact on the user experience. For the writer, it’s meant to be a time-saver, a set of pre-made decisions.
The problem arises when we confuse what is critical with what is merely conventional. Does it matter if we capitalize the word that follows a colon in a sentence? Perhaps only to other writers. We risk spending hours refining the rules for things that have little or no bearing on a user’s success, sometimes indulging in a sort of performative consistency that feels productive but delivers little value – at least not at the scale we might be currently locating ourselves. Is it fun, though? Oh hell, yeah, you betcha.
The same thing happens with style guides as with navigation menus: they help writers more than readers or casual contributors. In an ideal world you would have dedicated editors (I did work with a team of editors and it was a dream come true); if you can’t, then style guide enforcement should become a matter of automated tests or linting that catch style issues while you edit documents. Leave deterministic rules to linters and tone checks to AI checks. Read How to introduce prose linters at work for inspiration.
Alternative priority: Focus your style guide on what truly matters: consistent terminology, principles of voice and tone, guidelines on accessibility text. Treat it as a living document that codifies the most important decisions. If you can, automate most style checks using tools like Vale.
Premature componentization for content reuse is overkill
Writing once, publishing everywhere is a powerful idea. It paints a bucolic landscape where every snippet of text is a perfectly reusable component, and documentation updates happen with the click of a button. Merry Reuse sounds like pure, unadulterated efficiency. It’s also, for most of us, a trap, much like adopting Kubernetes at the earliest stages of software development. When it works, it’s wonderful; when it doesn’t, it’s a cathedral in the desert, an architectural dream turned into a nightmare of implementation.
I’ve been there, sadly. Before you can reuse a single word, you must first invest in a complex Component Content Management System (CCMS), a rigid DITA or XML schema, and weeks of training. Writing is no longer about crafting a coherent narrative; it’s meticulously assembling context-free LEGO bricks, hoping you’re building a car and not a lawnmower. The cognitive load on your writers skyrockets, and velocity grinds to a halt. I still stand by what I wrote in the Pros and Cons of Markdown:
We don’t use Markdown for docs because it’s better. We use Markdown for docs because most software companies haven’t even started their documentation efforts yet and we need a scratchpad every developer can use and understand. It’s a sociological choice, not a technological one.
Sometimes, though, this level of componentized complexity is necessary. If you’re writing for heavily regulated industries, where every warning label must be legally identical, the cost of inconsistency is catastrophic. If you’re managing documentation for a portfolio of thousands of similar hardware devices, the scale justifies the overhead. In these cases, content reuse isn’t overengineering; it’s the only sane way to operate. But in the world of software, most of these concerns don’t apply.
Alternative priority: Favor low friction to contribution. Focus on single-sourcing your data: pull things like API parameters and error codes directly from the source code. Use well-defined templates, but let your prose be prose. Wanna go structured? Hire a very good consultant.
Doc tools and pipelines are not the product, docs are
Among the many forms of yak shaving that plague our craft is obsessing over documentation tooling. The more technically minded among us are guilty of spending too much time tightening the screws of some CI pipeline just to save a few seconds when building the docs. As exercises, they’re indeed useful, for they help us practice technical skills that might lead us to becoming docs engineers. Should we park writing the docs over picking static-site generators though?
The danger lies in mistaking the motion for progress. A perfectly tuned pipeline that builds no new useful content is a monument to wasted effort. It’s the equivalent of a chef who spends all day sharpening their knives to a razor’s edge but never actually cooks a meal. The knives are essential, but they are not the dinner. Our tools are essential, but they are not the documentation. The user who is stuck at 2 AM with a failing API call does not care about your elegant build process; they care about finding the answer.
This trap is especially tempting because, like the style guide debates, it’s often more fun than the hard work of writing. This is why we see teams spend weeks in analysis paralysis, comparing the merits of five different static site generators when any one of them would have been good enough. This isn’t a technical choice; it’s a strategic one. And the winning strategy, as always, is to favor low friction to contribution. The best tool is the one your team and your contributors will actually use.
Alternative priority: Treat your tools like a plumber treats their wrenches. Pick a good enough set that gets the job done, and then focus on the actual plumbing. Automate the truly painful parts, like checking for broken links or linting prose for basic style, and then get back to work. The goal is not to admire the wrenches. The goal is to ship docs that don’t leak.
There’s a place and time for all of these activities
I’ve done most of the activities I’ve described in the previous sections – that’s why I know they’re often not conducive to useful outcomes. Did I learn wonderful things from those times? Definitely. Why, then, I listed them as things one shouldn’t be doing? Because it’s very easy to get to a point where those activities grow into time sinks. There’s also another key aspect, which is timing: most of the previous items are endgame pursuits, and only make sense when you’ve reached a certain level of maturity.
So, don’t feel bad if you’re doing anything of the above. Don’t drop your keyboard and run to your desk to rethink your priorities: rather, take this as a chance to reflect on how you can best deliver value. You might want to grow professionally or reach new intellectual depths. That requires time and energy, which in turn require prioritization. Decide what to focus on, then park the rest. As I wrote in Failing (and surviving failure) as a tech writer, seek the pangs of urgency. Seek the storms, not the gardens.