11 documentation writing tips that will save your life (maybe)

On a limited budget, it’s often about producing more documentation in less time – while still maintaining quality and usefulness. What’s a documentarian to do?

As with all processes, streamlining is the key to being more productive. This means automating as much as possible to free up your brain to concentrate on the important tasks.

There are other things you can do, too.

We’ve come up with these 11 tips to make your job as a documentarian much easier.

1. Crowdsourcing/allowing user contributions

Crowdsourcing the docs is a whole topic in itself, and one that we’ve covered in a previous post.

The first thing to be aware of is how you could be taking on more work than you anticipated. Managing an army of contributors is no simple feat. It’s an approach that works well for some companies and not so much for others.

Allowing your contributors to ‘suggest edits’ may be an easier route than crowdsourcing the whole thing. You won’t need so much of an editing process and it’s an easy way to achieve some quick wins.

2. Use productivity apps like Grammarly or Hemingway

What constitutes good writing is very subjective, but there are some tried and tested rules you can follow that will help make your documentation writing better.

• Shorter sentences
• Writing in active voice
• Shorter words
• Ditch the adverbs

The Hemingway app is an amazing shortcut to helping you learn the fundamentals of plain language.

Grammarly catches grammatical writing mistakes that your traditional spell checker won’t pick up on. It puts up a red flag when you use ‘your’ instead of ‘you’re’, and ‘days’ instead of ‘daze’. Stuff like that.

We cover the merits of plain language in a lot more detail in a previous post.

3. Save time with templates

Using templates to write your documentation is a surefire way to save time.

This doesn’t mean that all your content will be the same – rather, you will work from a consistent baseline and all your content will appear more related.

Create a shared template including examples of things like:

• Article headline
• Article subheadings
• Placement of images
• Paragraph length
• Style of introducing the topic

This will make teamwork a lot easier as everyone can work from the templates. This relieves the burden on the editor or documentation manager to standardize all the work.

4. Create a streamlined process

If you’re lucky enough to be producing documentation as a team, or even as a team of one, having a process gets things done much quicker.

A process is a way of doing things that you stick to repeatedly, time and time again. Beware of any bottlenecks in your process – obstacles that unnecessarily hold up achieving your team goals.

It’s as simple as automating or checking off the repetitive tasks and freeing up more room for creativity in the things that matter. When things are crazy, your process can really stop things from falling apart. It helps your team to scale.

5. Set targets and deadlines

As part of your process, make sure you decide when you’re going to get things done by. These deadlines can be fluid and changeable, but with a target to aim for you’ll have more momentum behind your work.

Having a deadline creates a measurable time frame which lets you know whether you’ve been successful or not. If you’re missing your deadlines, you know that something’s not working.

6. Use Trello boards

While apps can’t solve all your problems, the right ones can be incredibly useful in speeding up work – improving organisation and communication.

Many content teams use the productivity app Trello to manage their workload. It’s an organisational tool that allows you to arrange ‘cards’ into boards and columns. Each board can represent a team or a project, and each column within each board can be a stage of your process.

For example, you could create a documentation board with columns labelled ‘ideas’, ‘draft’, ‘2nd draft’, ‘final draft’, ‘published’, and so on. Different team members can be assigned to each card and you will be alerted when someone mentions you. You can include deadlines on your Trello cards too.

7. Construct your documentation in modules

Write your content in modules, which is also known as topic-based authoring.

Each content module should be self-contained and link up with other modules in a meaningful network. This reduces the chance of potentially having to rewrite whole swathes of your documentation in the future.

We’re getting away from the idea of writing the docs in an A-Z fashion, and more towards an alphabet soup. This makes Information Architecture all the more important.

It also means you can reuse some of your documentation in different formats and configurations, and cut down on the time you need to spend producing new content.

8. Focus on the most-searched queries

Accept that you’ll never be able to do it all. You won’t be able to create all the content you might want in an ideal world.

In reality, we can only focus on creating the most important documentation, right now.

A handy shortcut to producing only the most important documentation is reviewing your knowledge base search queries and making a list of your top user queries.

These are your quick wins – your low-hanging fruit. Creating content that answers these queries is most helpful to your users.

9. Create brand guidelines

If you haven’t already, you should create some brand guidelines that you can use to produce documentation.

Common in marketing, it’s a way of bringing together all the different components of your brand – copywriting tone, design colors and naming conventions, to name but a few.

This will be a document – or set of documents – that anyone can reference when trying to produce documentation for your company. It will make your docs appear more coherent to your users, and more professional.

10. Have a content strategy plan

Similarly to creating deadlines and processes, making a content strategy plan means you can tick off individual items instead of creating content haphazardly. It will be easier to track your progress and delegate each task.

A plan will also make your content more coherent for your users. If you develop a content plan, you’ll be taking your users on a journey.

Treating your product documentation like a journey will make it easier and more enjoyable to use.

11. Outsource it

If all else fails, consider hiring a freelancer or another team member to help with your workload. Outsourcing your docs can be a cost-saver if the agency or freelancer you choose is specialized and efficient.

If you need to convince management to allocate you some budget, tell them just how important your knowledge base is for self-service success.

Final remarks

We hope you find these hacks make your job a little easier. It’s an unavoidable fact that documentation is going to be challenging to produce, and you’ll probably be under-resourced, but that’s all part of the fun.

From using productivity apps like Trello and Grammarly, to streamlining your process and setting deadlines, to reusing your content and potentially outsourcing it, you can find ways to do more in less time.

Creating documentation that amazes your users will make the struggle worth it.

KnowledgeOwl offers dedicated knowledge base software to help you write your best support documentation. Take us for a free spin today.