5 tips to become a documentation champion

Maria Cerase
Jan 8, 2017 · 3 min read

“Our Wiki is incomplete and obsolete.”

“The feature was delayed because our documentation is bad.”

“If I had a penny for all the times someone asked me about the features in v1.2”.

Documentation seems to be development teams’ Achilles heel. Developers won’t do it, Product Managers scramble to keep up with the need for it, Sales, Support and Marketing teams are dying for it.

As an Agile Product Owner I have built myself a reputation for being a prolific, clear, relentless documentation champion and I want to share the necessary changes in attitude to become a documenation champion yourself.


1. Chase information like a shark

When something is not clear in the workings of your product, or you can’t locate a file or you simply don’t know if a functionality is actually there you need to chase people down. If the product is not well documented this reflects badly on you, don’t let other people sloppiness drag you down on your path to documentation paradise: ask, chase, be annoying if you must but get the answer you are looking for and write it in your wiki as soon as you receive it. Don’t wait a moment longer.

2. Don’t ever write the same email twice

Ever had a feeling of ‘déja vu’ while writing an email? Stop immediately. Go to your wiki, write down your answer there and reply to the email with a link to the article. Make sure as many people as possible are in cc, show that you don’t write adhoc emails. You mean business with keeping your section of the wiki up-to-date, and people are better off searching before sending emails.

3. ‘Ohhh I didn’t know that!’

Sometimes it’s you who’s on the receiving end of information. On a chain of emails involving your tech team, you find out that your server has a very cool logging system that nobody knew of, but that’s absolutely worth knowing! Whenever you tell yourself ‘wow, I learned something today’, write it down. Go to the wiki and find a space to type it in. If you got time to procrastinate reading on the latest spoilers of Game of Thrones, you can write a tiny line of documentation. Go now!

4. Don’t send attachments

Beside the fact that I hate attachments as I lose track of the modifications people do to the original document, you simply shouldn’t send them. Next time a sales guy comes to your desk looking for the latest deck about the features of the latest release, ship him off tothe wiki where he will be able to download it from a folder dedicated to this sort of stuff. Attachments are garlic and you are a vampire: keep away and stay safe.

5. Something is better than nothing

If I had a penny for everytime someone didn’t follow through with the promise of documenting a feature, my new kitchen would have paid itself. Beside holding people responsible for their promises, don’t wait and just get it started yourself. Even if you are not the right person to create a technical diagram, ask yourself: is it better to have nothing or to have something imperfect? I found that by starting something myself, I got developers way more interested. If you show them the way they will follow.

These are some of the principles I created for myself. Print them, write them on a post-it and stick them close to your desk. Whenever you have that feeling of repeating yourself, or that you’d really like having something written about the product, don’t wait. Just write it.

Maria Cerase

Written by

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade