Write the Docs – How to turn a freight ship around when all you have is a paddle by Elina McCafferty

Elina McCafferty gave a talk at Write the Docs Vilnius about how 'How to turn a freight ship around when all you have is a paddle'.

Elina has been a technical writer for 14 years, and her current job involves dealing with a large amount of legacy documentation. Her talk was about how to rewrite enormous documentation sets that you don't really have time to rewrite, especially since you also have to keep creating new documentation for the software. 

Elina's team works in Agile, where you have to document alongside the engineers and they develop features. This means you can't even stop documenting new features as you tackle the freight ship.

The problem

The software at Elina's company has been around since 1985, which was when you'd hope they also started writing the documentation. Most of the documentation was written by engineers, as was the custom at the time. Their documentation is thousands of pages long, and the team tries not to look at the overall number of topics.

Their documentation has grown over years and years, and in some cases legacy docs might even be older than you are. At Elina's company, the user orientation focus has only really been a priority in the last decade or so. As a result, many of the old docs desperately need updating. 

Unfortunately, as Elina says, you identify a weak spot that you want to work on, which means you start unravelling the thread. You discover there's a rabbit hole with a tangle of topics together, and suddenly you've lost your focus. 

Sometimes the issue is poor quality content that's difficult to fix, since it has grown organically and the information has fragmented. 

How to tackle legacy docs

Elina has a quickfire list of tips of what to do in these kinds of situations: 

• Manage your top level nodes
• Manage your paths
• Tidy up last-minute content

"Make the right small changes," says Elina. You should focus on the little wins:

• Tangible improvements
• Scalable approach
• Low effort, high impact
• Each iteration moves you forward

At the very least, you need to manage the first impression you're making with your users. This means getting your navigation nodes, article titles, and article introductions perfect. 

The reason for this is that it's human nature to find flaws and generalize from that first impression, which causes you to start looking for other flaws. A user's comfort zone comes from having confidence in the documentation. 

It's human nature for first impressions to count

You need to be able to contact your users, even if indirectly, in order to improve the documentation and find out the problems your users are having. Get hard data if you can by installing analytics on your web help. But just because users are going to a particular page, that doesn't mean it was where they intended to go.

The 80/20 rule

When tackling your legacy documentation, follow the 80/20 rule (also known as the Pareto principle). This means that 20% of your rewriting efforts creates a disproportionately large impact. It also means that 80% of your users care about 20% of your documentation. 

For example, Microsoft cut 70% of their documentation about Excel, and their customer satisfaction went up. Pick the top 20 topics that you need to rewrite in your documentation, and work on those first. 

Pick your top 20 topics to work on

Make sure your top level categories in your table of contents of your documentation are correct, and that your topics inspire confidence. Your prospective customers will be looking at these. 

You can place your more specialist documentation further down in your navigation. Users who need more niche information will be okay with drilling down through your content hierarchy, while beginner users might be put ill at ease by information that's too in-depth.

If you're out of time while working on these things, at least tidy up the content with a meaningful descriptive title, good intro, and clear structure. It won't hold for long, but it will help you get through the first iteration. Leave the proper rewriting for later.

Managing your psychological state

You need to manage your psychological state during this process by having a structured list of topics. Create a realistic timeframe to complete the work, and use these two categories: quick fixes and big fixes. You need to give yourself little wins along the way, since the end result is so far away (measured in terms of years).

"Use the Agile mindset to your advantage. 'Working software over comprehensive documentation' (part of the Agile manifesto) has a lot to answer for," says Elina. It's led to a lack of discipline in producing customer documentation. But in this case, you can reinterpret it to be: 'Working documentation over comprehensive documentation.'

"Examine your own drive for perfection," Elina says. It can hinder you when it comes to the level of quality of what you're documenting. You might need to switch off your tendency for perfectionism for your own wellbeing. 

Sustain yourself throughout this project

No news is good news

As your documentation improves, you might not get positive feedback from your customers, but the number of complaints diminishes. Silence is a really good thing in this case, but it can be lonely and unrewarding. 

Luckily, conferences like Write the Docs have a psychological value in highlighting that we all deal with these same issues. "Over time, your drops change your tide," says Elina. 

Connect with Elina on LinkedIn. Now, why not check out our general write-up of Write the Docs Vilnius?

Our very own knowledge base software KnowledgeOwl can help you create delightful documentation for your users. Take it for a free spin now.