How to get carried-away with documentation

Nearly anyone in IT can tell you that documentation is pretty important. Unless you’ve been living under a rock, you’ve probably heard this saying:

“If it isn’t written-down, it didn’t happen.”

When I think about the two extreme edges of documentation, I think of two groups.

  1. People who don’t do documentation and avoid it with every fiber of their being.
  2. People who get carried away with documentation and make messes that provide decreasing ROI (or worse).

You would think that these two groups are somewhat rare in a world that is becoming more savvy with technology. However, they do still exist and at some point in your career, you may encounter one or both. When you do, you will probably see it as a problem that needs to be fixed.

Take a moment to consider the causes for each: One requires no effort and the other requires unusual effort. The reason for laziness, is pretty obvious. However, it seems very interesting to me, that someone could expend great efforts to over-do-it with documentation without producing a good result. It is a lot of work to make a mess. How does that sort of thing happen?

People who get carried away with docs (and make a mess) are usually one (1) of the following:

  • You are new to documentation and you dive-right-in. You are not clear on how to be organized but you figure that you can learn about it as you go. You expect to have it all figured out pretty soon.
  • You are getting paid to do documentation. There is nothing else to do. You just stay busy so you keep getting paid.
  • You think that you are being “graded by the pound”. It worked in school, or in your last job. You got an A for all of your extensive & hard work and diligence. So, you are applying that same mentality as you crank out some docs. You find it hard to believe that anyone will see this as a useless mess because, golly, you are building the empire state building out of docs. I guess haters gonna hate.
  • You are a hoarder. Documentation has a value, so you will go cuckoo by collecting embarrassing amounts of it.
  • You are the kind of person who works harder, not smarter sometimes. You have a drive to constantly start something new (not always finishing it). Somebody else will organize it later, if it really matters so much to them.
  • You need to be introduced to the concepts of optimization. When “less is more”. Stuff like that. It sounds contradictory. You don’t think it would apply to docs.

If you are one of these types of personalities, then you should be careful as you approach documentation. Find someone to help you stay grounded so you don’t run amok.

You can be relatively confident that you are not making a mess, if you look for the signs that your docs are “just right” and not out-of-control:

  1. Other people find your docs to be useful (more than 2) (not-including your spouse, bestie, or mom)
  2. You are working towards a goal. Once you achieve it, you will stop, evaluate, and refine before proceeding again.
  3. Your docs are organized and easy to find, navigate and use.
  4. You are actually measuring the use of your docs, so you can physically prove/show that they are providing value (which ones are being used, and which ones are not).
  5. You have a plan about when to review/revise/revisit them to make sure they remain timely and relevant.

If any of these 5 points are a little “iffy”, with your docs, then you probably need to take a time-out and reevaluate your goals/plans.

About Tim Golisch

I'm a geek. I do geeky things.
This entry was posted in Documentation, Methodology. Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s