What does it mean to fail as a technical writer? How does one get up again? How can we correct course and rekindle the fire that helped us power through rejections, layoffs, and ostracism? Is there any switch we can toggle so that folks understand what it is that we do and provide us with the resources we need in order to contribute a verse? I’ve been thinking about all this since I became a tech writer; now I want to share some of those thoughts with you.
Hopefulness is not a neutral position. It is adversarial. It is the warrior emotion that can lay waste to cynicism.
– Nick Cave
Those who write in tech are quite vulnerable to failure. Unshielded from the whims of technological trends and the dangers posed by mindless automation, technical writers constantly seek to reinvent themselves and adapt to ever changing landscapes. We are the wandering polyglots, doomed to understand all programming and design languages yet master none as we roam the wastes of broken products and alienating interfaces.
And yet we keep writing, fully aware that without our words and the human ingredient we bring to the mix, technological innovation would land on people like a massive cudgel made of good intentions. Although we bridge the gap between silicon and carbon, we often feel that we’re the only ones that realize the value of what we do, that the obstacles we pulverize through text alone are invisible as long as we’re around. (Hint: It’s not true.)
In this context, failure becomes almost a way of life. We fail to convey the importance of words. We fail at getting the attention of decision makers. We fail to change the ways of orgs – because how else do you attain a change in how a product communicates if not through an organizational change? Sometimes we give up and fail to change our ways, or we go the opposite way and bury our pen under the sand, eager to embrace simpler quests.
What follows are the four main types of technical writing failures I witnessed – and sometimes suffered – throughout my career, and what I think are the best ways of getting past them.
In my career I failed numerous times at convincing stakeholders and higher-ups that more resources were needed for technical documentation. People listened to my arguments and requests, then nothing happened. I then insisted a few more times, until I started looking for another job. It had never been a heated debate — it was more like getting an uninterested “Hm-mm” from a friend who isn’t really paying attention.
In hindsight, the fact that they agreed to listen at all was a good outcome, but I had been unable to perceive the hidden agenda of the people I was pitching better docs to. Sometimes, their worries were opaque; other times, they preferred to dedicate resources to other things. Perhaps if I had documentation observability in place I could have brought more impressive metrics to the table and more convincing arguments. I did accomplish significant change at times, almost always self-powered, but not all the change I wanted or needed.
One of the solutions, I believe, is to increase the visibility and respectability of our craft. I started this blog with the intention of providing writers with resources for the kind of discussions I described previously. I think technical writing, as one of the many faces of humanities in tech, deserves greater visibility. That can only happen if technical writers become prouder and more vocal about their craft. As I said and continue saying, we should be blogging more.
Think about why you love this job, then let the world know. Your voice counts.
There are moments in the life of a technical writer made of merry stability: We’ve finally landed a good job and started tending to our garden of words, progressively isolating ourselves from the struggles happening around us. In such an idyllic oasis of grammar, we occasionally get news about the rise and fall of products, little dramas that end up in release notes and admonitions, only to be forgotten as soon as someone sends a docs feedback ticket to the queue.
As pleasant as it may seem, the cenobite phase of technical writing is ripe with opportunities for failure. Immersed in the sureties of docs debt and weekly release notes, I, too, failed to focus on the things that would have made the difference or mattered the most. This is not to say that business as usual or maintenance work is useless, but there’s a numbness to it that makes it difficult to look outside of the cloister and perceive the needs of users and stakeholders.
This kind of failure could be avoided by either embedding technical writers more into product teams, hence making them co-responsible for the success or failure of features, or by having documentation managers, if they exist at your workplace, drive and crowdsource priorities in the team. While it might make sense for team managers to follow management practices and play the serene shepherd, I think they should inject more “why” into the days of their managees.
If you’re not feeling pangs of urgency in your work, seek them out. Seek the storms.
Perhaps as a consequence of spending years and years in the merry garden of words, many technical writers end up feeling somewhat contemptuous of non-writers. They know their craft well, they have a decent track record of saving the day through resolute, if a bit unoriginal, docs updates. There might have been a time where they sought developers and product managers for advice and collaboration, but not anymore. They’re senior now, whatever that means, and that’s enough for them to shun anything lying outside of their turf. How sad.
The unwillingness to mingle and blur the boundaries of our work is a spectacular way of failing as a technical writer. Our job is that of a bridge: We connect functions and teams and products through words and concepts. Some don’t think that way, though. Recently, someone said elsewhere that “the code base isn’t a good place [for devs and writers] to bond”. I think everywhere is a good place for tech writers and engineers to work together. As much as we’d like to appeal to our authority, the truth is that we can’t do that.
The docs-as-code ethos is born out of the premise that developers and technical writers can work together using the same languages, tools, and repositories. Even if one doesn’t work in docs-as-code projects, its principles apply to modern software development. All technical writers should act according to the belief that their job title is but a specialization of a single, universal role, which is software developer, because software is also made of words.
Challenge yourself to cross the boundaries of your role in healthy ways. Be an ambassador.
Technical writers, like developers, risk becoming too attached to tools and methods that worked well for them in the past. We become attached to DocBook, DITA, Confluence, Gatsby, Markdown, Asciidoc… until one day we find out that the times have changed and require a different toolchain and a more flexible mindset. What worked before might not work in the future. And when I say work, I mean “as an enabler of human collaboration”.
As 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 it’s a language that every developer can use and understand from day one. When it comes to content strategy and toolchain decisions, the key factor is almost always sociological, not technological. We follow and attach ourselves to existing stacks (rST for Python is a good example) because we need subject-matter experts to dump their brains into drafts as fast and accurately as possible.
Attachment to tools and markup languages, while understandable from the point of view of career growth, can become a liability in the long run. Instead of hyper-specializing in the usage of a tool or trying to master a language, focus on extracting lessons and transferable learnings from the combination of tools and goals that you’re going through. If DITA disappears one day, the underlying lessons in content reuse and structured content could still endure and pass onto new stacks – like, for example, a JSON schema for Markdown docs.
What matters is the goal of helping users and products. All else is transient.
As you might have noticed, I haven’t focused on things like not knowing enough about a piece of technology or not looking enough at analytics. I haven’t because I believe failure is always systemic. The majority of tech writers I know try hard and do their best at an individual level; it’s what surrounds them, and their reaction to that environment, that determines “failure”. In this sense, failing is not being able to exit a certain zone where we lack power or resources.
As tech writers we usually know what works best for docs, but we’re often not in a position to steer engineering or product orgs on our own. It’s a labor of persuasion and patience. It’ll always be — at least until we get Chief Documentation Officers to be the norm. Don’t count on that though: the time of Chief Knowledge Officers and similar positions that used to be present in org charts is waning. Software development has a very short memory.
Ultimately, failure isn’t a flaw in our abilities but a reflection of the systems we navigate and the influence we can exert within them. It’s the disconnect between what we know is necessary and what we’re allowed to accomplish. The path forward lies in continuously expanding our influence, advocating for the visibility of our work, and bridging gaps between disciplines. We must persist in redefining the narrative around technical writing, turning our perceived failures into opportunities for growth. The future of our profession depends on it