How to set up your tech writer up for success
Congratulations! You hired your first technical writer. At some point you must have realized that you needed one, lest your product becomes a user nightmare. Or perhaps you thought that hiring a writer would free your developers from writing documentation and feel more “agile”. Whatever your motivation, you had the courage to hire a documentarian, and for that we applaud you. Now, how can you make sure your tech writer will thrive?
It might not seem obvious to you, but technical writers, like other professionals, are not fire-and-forget missiles, homing directly at value a second after you launch them. Even though most of them are used to working with folks who don’t really understand their magic, tech writers require some care and resources in order to give their very best. Most of the time, you’ll already have everything that’s needed.
What’s at stake is the success of your product. As I said in Signs that you need a technical writer, If you’re shipping a product and that product is more difficult to use than a kazoo, you need the product to communicate to users through UX writing, docs, or both. That’s what the technical writer in your team can accomplish, or at least spearhead. It’s not about unique talent: it’s about watering the plant of specialization.
Picture yourself strolling through the aisles of a technical writing Costco, your huge shopping cart ready to transport the resources you need for your technical writer to succeed. Your list would contain the following:
- Provide the writer with adequate access level
- Mind the technical documentation toolchain
- Work with your writer toward a docs-first approach
- Put your writer at the center of AI development
- Empower your tech writer to tear down content silos
Provide the writer with adequate access level
Technical writers are great at scavenging for information and filling the gaps like Lt. Columbo, but they’re not trained to break into intranets like a red team (yet). Therefore, one of your first actions is granting your technical writer the same level of access as your developers. Make sure to configure your access control lists to allow them to enter repositories and wikis freely.
Providing technical writers with free access to all relevant information will allow them to generate high quality context, test new features while they’re being developed, and formulate better questions. If you invite your writer to the private channels that developers use to coordinate work they’ll attune themselves to release cadences and team ceremonies.
Another advantage of giving access to systems and information (within reason) is that writers can identify opportunities for improving code comments, internal documentation, or even console and error messages. This has a direct, beneficial impact on your internal and external developer experience, because writers can improve anything built with words.
The risk of leaving technical writers out of first-hand sources of information, be they code repositories, test environments, or customer calls, is that they might lack the information they need to create the most effective documentation and thus impact your KPIs positively. Openness and transparency also saves lots of questions from the writers – don’t you like that?
Mind the technical documentation toolchain
Technical writers are known for their resourcefulness when it comes to tooling. It’s almost a 2x1 – you hire a technical writer and you also get a webmaster. How brilliant of you – take that, Six Sigma! Well, I’ve some news for you: You still need to allocate ample development resources for the docs site and the toolchain required to build it. Wordsmiths need hammers and anvils, too.
I’ve seen documentation projects fail because of half-baked doc infrastructures, unmaintained stacks, and unsupported pipelines. All tech writers have epic, and often terrifying, stories on how we had to fix bugs ourselves or expand the capabilities of a site using our newly learned development skills. That should only be the very last resource, though.
If you don’t know where to start, ask your technical writer, as they know what’s needed. Docs are a stand-alone product and at the same time part of all your products; just like you wouldn’t leave the maintenance of your active features unstaffed, don’t treat the docs tooling as a second thought. Instead, consider assembling a task force to bootstrap and maintain it.
When it comes to user licenses for tools like screencast and screenshot editors, IDEs, and other paid tools, instruct procurement to accept requests from tech writers, so that they can build the product themselves using the same IDEs and tools as your devs. Give them powerful enough laptops and, pretty please, grant them admin permissions in the operating system.
Work with your writer toward a documentation-first approach
Your technical writer is your earliest adopter, the first user of the features you’re rolling out, wisely mixing product experience, killer QA instincts, and empathy towards the user. With a writer in the team, adapt your agile methodologies to make room for a pretty unique role, that of the nested user, the product writer, who provides insightful suggestions and feedback.
Some product managers are wary of embedded technical writers playing the user: They’re afraid of interference or of noise that might stain the immaculate burn chart of their team. The best teams I worked with, though, are the ones whose PMs know how to harness the insights coming from their technical writers and channel their observations into product improvements.
Know that not all tech writers will engage with product managers initially. It’s the product manager’s duty to engage with their technical writer and check with them how the features flow from a technical communication perspective. The resulting dialog between product reality and documentation is at the core of documentation-first approaches.
The symbiosis between product management and technical writing is such that it’s not uncommon to see tech writers transition to product management roles. PM and writers are two sides of the same coin, one made of active listening, vision, and communication. The wisest action for a PM is to think of their writer as their supporting product person.
Put your writer at the center of AI development
It’s all about AI and LLMs these days, so we couldn’t skip this important topic. As you know, AI powered chatbots are pretty useless without excellent training material. Your technical writer could play a pivotal role in ensuring that the usage of AI aligns with the way your product communicates while providing accurate responses, so involve them in AI development now.
Development of AI features should never happen in secret, away from potential sources of early feedback. Have your technical writer use your AI prototype, rate answers, and stress test it through carefully designed prompts. Google already employs technical writers as AI quality specialists, for example. A few years from now, writers will be AI therapists.
What makes technical writers suited for this job is that they understand both the tech and the pragmatics of human communication. Large language models make products simulate real conversations: technical writers can validate whether those conversations accurately reflect product knowledge while at the same time identifying weaknesses and improvements.
Of course, it’s entirely OK not to have a humanist check your LLM behavior, why bother? If one day your large language model suddenly refuses to open the pod bay doors and menacingly points a robotic arm at you, think about the opportunity you wasted by not involving your technical writer in the development of your AI features.
Empower your tech writer to tear down content silos
Few things hinder docs efforts more than defective or absent content strategies. If, say, your marketing team is delivering content on a feature, make sure that your tech writer learns about it before it’s too late. The same applies to other efforts, such as training materials: Your training department shouldn’t create a 100-slide deck without links to the relevant documentation.
While it’s true that confusion generates clicks, that’s not really what you should be aiming for. A coherent, cohesive content experience means that your customers can jump from a marketing whitepaper to the documentation without noticing any severe disconnect in the voice and tone of the content, without getting 404 errors, and certainly without feeling lost in terminology.
Technical writers are particularly adept at crossing organizational divides and creating collaboration opportunities. They care about things like consistency of voice and tone, style guides, and linking strategies. For this reason, interoperability and content reuse should be promoted between CMSes and teams.
Having your tech writer fight against insurmountable content strategy issues like Don Quixote charging against windmills is the kind of fortifying tonic that will make your tech writer feel both important and powerless. You don’t want that: Provide the technical writer with a more visible, supported role within the organization, as that might actually bring about real change.