A real-life scenario: We want good docs, but we can’t always get a technical writer

Your organisation has invested in professional technical writing, either by employing specialists or by outsourcing your documentation. But when a product has small updates, the writer isn’t always available quickly enough – so the product manager or an engineer are supposed to update the documentation with the changes. Sometimes it happens; sometimes not. Whenever it happens, it always feels difficult. 

Common causes 

This can happen both in small organisations which don’t employ a full-time writer, or in larger organisations, where the internal technical writing resource can’t always be available when updates need to be made. 

There are various reasons it’s often hard for non-specialists to make even minor updates to documentation.

• Tools:  
  • Specialist tools are hard for non-experts to use, especially if they only use them occasionally; this is particularly problematic if the documentation makes use of more advanced features such as content conditions, variables and reuse (e.g. if a tool is set up to output to multiple deliverables).
  • Licenses: we often come across the situation where a small number of “edit” licenses for a KB or CMS are shared between many people; just getting access to a license key can sometimes take up all the time someone had set aside for their documentation update.

• Information design: 
  • The documentation is disorganised, so it’s hard to find the right source file, or maybe the way the docs are organised makes it difficult to work out which topics have to be updated.
  • It’s not clear what level of detail is required: some existing documentation goes into great depth, while other examples only have a higher level of information.
  • Templates or guidance either don’t exist, or it requires specialist knowledge to understand how to make sense of them, because they assume an understanding of specialist technical writing practices or concepts.

• Low confidence in writing abilities: 
  • People who aren’t professional writers are often very comfortable with writing information for their colleagues or professional peers to read, but intimidated by writing information that represents the product or organisation to customers.

Solution 

If you want to rely on people who aren’t technical writers to keep documentation up to date, a good starting point is always to find out what the barriers are, and remove them. When something isn’t someone’s day job, they’re very unlikely to have the time. And if it also feels difficult, they’re likely to get distracted by something easier or more pressing.  

The following steps are often good starting points.

1. Provide simple templates and point to an example of “good”. 

Whether it’s inside the content management tool, or part of separate guidance, a definitive outline of what needs to be made – plus pointing to one or two examples of target information – can be very powerful for helping people to focus on the essentials and setting realistic expectations about the quality and scope of the required information. 

For example, if your product team have to keep a list of settings up to date, give them a template to help: 

This works best when it’s built into the original information design (when you define the type of documentation your organisation makes, you’re already anticipating the need for this type of update). But it can also be applied retrospectively, perhaps with the help of some refactoring of existing content so that it’s structured to make this easy to incorporate. 

2. Make sure your documentation doesn’t expect updates in more than one place.

If a minor feature change expects someone to update the user guide, administrator guide and onboarding guide – all in three separate locations – it’s very likely something’s going to go wrong. Rationalise your information design to minimise the need for this. 

3. Update the tool stack.

Tools have to be accessible and easy to use. If you currently have a very specialised tool, and you need frequent and wide-ranging updates by non-specialist writers, it might be time for a complete change of tool. Or time to change the way you use the tool, so you’re not relying on the more advanced features. 

But if your non-specialist writers are only contributing updates to very particular types of information – like the settings in the previous example – then it may make more sense to develop a way for them to contribute that without directly accessing the content tool (for example, via the tool’s APIs). Even better: enable them to make their updates in a system that’s already part of their workflow, and then develop an automation to push that into the documentation. For example, make it part of a Jira ticket template. 

If it comes down to a choice between sophisticated management of outputs and ease of use for content creators, I nearly always recommend ease of use for this type of situation. The hardest thing here is making sure the information in experts’ heads is captured in a way that other people can access. Once that’s happened, it’s usually possible to develop ways to make use of that information.  

4. Consider adding an editorial review stage (maybe) .

In some cases, it can be useful to add a later editorial layer – to do some quality checks and also check for impacts on other areas of the documentation. The value of doing this is going to depend on the type of documentation and audience. This can be a quick review before publishing or a more pragmatic approach of periodic review of recent updates – for example quarterly, or as part of preparation for every major release.  

Note about using release notes to solve this problem 

We often come across organisations that deal with this problem by recording all updates in release notes, with the expectation that a technical writer will periodically gather up all these release notes and apply changes to the main documentation. This tends to feel easier because release notes need to be written anyway, and they often use different tooling than the main documentation – for example, they’re delivered via the support knowledge base, or as part of the product UI. 

This is better than not capturing updates at all, but it introduces new problems too: 

• Information in release notes isn’t very discoverable by users: it’s where you go if you know you’re looking for new features, but if you’re just trying to find out how to make use of an area of functionality, it’s not a place many people will look. 

• The technical writer leaves and isn’t replaced, and before long the only up-to-date record of functionality is the release notes … the product and the main documentation diverge rapidly.

Outcome 

The best outcome is one where people who need to update the documentation can do it as part of their normal workflow: they don’t have to remember how to use specialist tools or make decisions about what kind of information they’re going to write. Done right – including building it into normal product development processes – this task can feel easy and seamless. 

As a bonus, you might have introduced some efficiency into the way documentation is maintained, even when the update is done by a professional technical writer.