Minimum Viable Documentation – the art of documentation triage

Catherine Heath | May 16, 2018

At his talk during Write the Docs Portland 2018, Senior Technical Documentation Manager at Splunk Neal Kaplan educated us in the art – or craft – of documentation triage.

So what exactly does this mean?

What is documentation triage

It means prioritizing your docs so you can get through the most important work first, so if you run out of time then you haven’t delayed over something crucial. It means accepting that you won’t be able to do it all.

Every technical writer is short of time to create documentation. No one has ever heard of a technical writer with nothing to do. We are constantly up against the challenge of creating more docs with less time and maintain quality.

The answer?

Minimum Viable Documentation

Minimum Viable Documentation is another way of saying don’t strive for perfection but rather documentation that is good enough.

As Neal says, “Perfect is not the enemy of good; perfect is the enemy of done.”

This talk says a lot about the status of technical writing within the tech industry and beyond, but also how there is a pressure to do more with less time.

So how exactly do you triage your documentation? “Identify critical high-value documentation needs,” says Neal, “and prioritize ruthlessly.”

How to tackle problems

The problem we as technical writers face is that, early on in your career, you think everything is important. This leads to jumping in at the deep end and making needless mistakes.

Instead of strategic planning, we opt for techniques like “firefighting”.

As Neal says, “Avoid the documentation equivalent of pointing a lightsaber at your face.”

Here are several more of Neal’s practical tips for implementing documentation triage into your workflow:

• Start planning before you dive into writing

• Audit the existing documentation and identify gaps

• Give each task an estimated level of effort – you will be wrong but you’ll get better

• Stand by your plan but also be flexible

• Architect your docs – start small and plan to grow

• Write, iterate, improve.

Develop a good feedback mechanism

If you’re the only person responsible for your docs and you’re feeling burned out, you can risk becoming quite precious about the quality of your work.

Neal shared his own experience of getting to the point where he was discouraging feedback from his colleagues. Luckily, one of them shared this with him and he was able to change his ways.

Accept all criticism and feedback with honest appreciation and don’t take the docs personally.

If you take criticism too personally, then your coworkers will stop giving you feedback and the whole system will break down. Your ego stays in tact but your docs are way less than perfect.

Make the effort

Documentation doesn’t exist in isolation, though it can often feel that way. Neal is an advocate of making everyone in your team a documentarian in some fashion.

Information never falls in your lap and “never accept that our users will understand,” Neal says. Always remember to ask, who am I writing for?

If you have managed to avoid alienating your coworkers, go one step further by trying to make friends with people who work with customers. This can include customer support but also sales and marketing.

Ask product management why they are building the product and ask marketing who they are marketing the product to. Take a lot of notes when researching your documentation because you will not remember things weeks later

Remember – the documentation is your product, and you own your product. Don’t be afraid to push your own agenda.

Final remarks

There will never be time to do everything you want to do and this is particularly true for technical writing. Documentation triage is the answer to having too much work to do.

Create strong networks with your colleagues and never stop asking who your user is. Everything will take longer than you expect, but you will improve with time.

“Experience is learning what you don’t have to do.”

Listen to Neal’s full talk on YouTube, or check out our other write-up on hiring junior technical writers. 

Images by Kay Smoljak. This work is licensed under a Creative Commons Attribution-Non Commercial-ShareAlike 2.0 Generic License.

KnowledgeOwl is our very own knowledge base software, perfect for technical writers of many stripes. Take it for a free spin.