The Top 5 Reasons to Skip Documentation (But Why Should Write it Anyway)

Write documentation. We’ve all heard it, but few of us do it. Why?

We’ll it’s pretty easy to justify skipping it. In fact, it’s easier to justify skipping it that writing it. Ben Mullins, the author of the article this post is based on, says it well:

Somewhere in the back of our minds, everyone working on a software project is aware that documentation is a very good thing to have. Despite this awareness, documentation is often prioritized lower than it should be.

Well, this post is dedicated to celebrating those top reasons to skip writing documentation (and discuss why you should write it anyway).

Let the celebration begin with a countdown to the #1 top reading to not write documentation!

5) I’d Rather be Coding

As a developer I can sympathize with this one–building something new is always more fun. But think about it this way: every 1 hour you spend on documentation will save you 2-8 hours of explaining, meetings, emails and other time wasters to spend on something else. You know, like coding.

4) I’m Too Busy to Write Documentation

Related to the above response, you’re too busy not to write documentation! In the long run it’ll save you more time than it takes.

Finding time to write documentation is always a challenge, so do your best to schedule it.  HIP sprints and flex time are great for this.  It could even be included in your release cycle.

3) Customers & Managers Care More About New Features

This is true, but documentation is what helps users get the most out of features.  Besides, there’s nothing more frustrating than struggling with an exciting new feature you can’t figure out how to use.

2) It’s Hard to Measure the Benefits of Documentation

Documentation is more preventative rather than a direct value add.  Like with insurance, it’s hard to show the benefits until later.

The easiest way may be to look at meetings, emails, customer support requests, etc. that could be avoided by adequate documentation.  Not only does that save time and money for the team, but it would have been a better experience for the customer.  How valuable is that?

1) Nobody Is Going To Read It Anyway

Sure, from time to time there may be a page of documentation that nobody reads, but in our experience that’s rare when implemented correctly.

Besides, that problem is usually solved by encourage customers and team members to use documentation.  It’s a habit.  Encourage the habit by linking to it when customers or team members ask questions covered in the documentation.

Closing Thoughts

Solid documentation is valuable, but often underrated.

Although it is not at all flashy, and not an ideal way to spend an afternoon, the benefits are enormous.

The article this post summarized, Documentation: Writing it is the Worst, Having it is the Best, is one of the best I’ve come across. If you’re obsessed with knowledge management like I am then check it out for more.


Also published on Medium.