Don’t Mess It Up: Write It Down

“The faintest ink is more powerful than the strongest memory.” — Chinese Proverb

Documentation isn’t sexy. Most people I’ve worked with haven’t particularly cared for it, and it is inevitably one of the first things to be sacrificed when deadlines loom.

Teams can often go weeks or even months without feeling the impact of that short-term thinking. However, the long-term downside can include lack of consistency, reduced efficiency and heavy reliance on institutional knowledge, which in turn means increased dependency on key resources that may be difficult to replace.

Perhaps worse still is that failing to capture why something is done the way it is can lead to rote repetition of a task even once its purpose and value are long gone.

Early in my management career I inherited a team that was responsible for producing monthly reporting. It was time consuming, tedious work that kept us from innovating and improving. Wanting to understand its importance, I dug in with the help of my team. Nothing was documented. All we had was a checklist of steps and a folder to copy the file into on the due date.

One month we tried the classic “see who complains if this doesn’t happen” tactic. There were no complaints. The next month, the same thing – and again no complaints.

Eventually someone did ask about the report – and it turned out they only needed one number, quarterly.

Of everything we had done on a monthly basis, only about ten percent of that work was necessary, and much less frequently. I’m sure the report had a valid purpose at one point, but without knowing what it was and without good habits for revalidating the need, organizational drift created a significant inefficiency.

I suspect everyone who has put in a few years in a large corporation has a similar anecdote.

So, what can be done about it? Can good documentation habits be established in a sustainable way for long term success?

Sustainable Documentation

Here’s what I’ve seen work well on multiple teams.

Plan for Documentation

Make creating or updating your documentation part of your work estimates and plans. If you’re a team that uses Scrum or some other flavor of Agile, include documentation as an acceptance criteria. If you use traditional project planning methodologies then include documentation tasks. Do a documentation review the same way you’d do a code review.

Use a Central Repository

Use a searchable repository for documentation. Something like Confluence or SharePoint works great. Having a central location that people know has tons of useful information and can be easily searched means people are more likely to use the documentation that is created. Documents on shared drives or relying on email is better than nothing – but unlikely to create the habits of creating and consuming documentation that you want the team to have.

Review Regularly

Establish a periodic review process. At whatever frequency makes sense (I used twice a year) divide up the existing documentation amongst the team for a review. Switching up who reviews which documentation helps with awareness and knowledge sharing, and allows a new perspective.

At the beginning you may want to provide some guidance as to what they’re looking for, so it doesn’t become a rubber-stamp approval. Is the documentation up to date with the current processes and tools? Is it clear? Does it explain why what’s being documented is important?

If you’re using a tool like Confluence or SharePoint you can have the reviewer add the date of review as a page property or metadata tag and automatically create reports of which pages are due for review, which have been recently reviewed, which need updates, etc.

Prioritize What Matters

Designate what documentation is important enough to keep up to date. Not all documentation is created equal. As a team decide what is worthy of periodic review. Label these so that the documentation review report described above contains only the pages which require review.

Answer With a Link

When questions come up (especially if the same question comes up frequently), put that answer into your documentation repository, and provide the link to the answer along with your answer. Make this a team habit. It encourages people to document, and it encourages people to use that documentation.

This sounds like a lot of work…

Depending on what your starting point is it might be a significant effort to set up initially. But it is an effort that will pay off in the long run with faster onboarding time for new team members, increased team efficiency, more consistent work product and more effective knowledge sharing across team members.

Effective documentation isn’t just about preserving the past – it creates space for teams to innovate and focus on the future.

A little effort twice a year is enough to keep the ink fresh – because even the strongest memory fades, but good documentation lasts.