Hang on to that owner’s manual

Even systems that work very well can be really hard to use without good documentation.

---

Spring is here, and it's time to groom the lawn.

I bought a gas-powered line trimmer a few seasons ago. Weed-eater, grass-whacker, whatever you call it, yesterday it was finally time to dust the thing off.

But the darned thing was fresh out of line. You know, the little plastic filament that actually cuts the weeds — it had just run out.

No problem, I thought, I've got extra line. I'll just wind it onto the spool.

Sorry, not so fast. I just could not figure out how to open up the spool and load the line, even though I’ve done it half a dozen times before.

Fortunately, I have the owner's manual filed away somewhere.

It took me a minute to find it, but once I had that in hand, the whole thing was easy.

I'm not winning any neighborhood awards for Best Kept Lawn, but at least now I can tell where the driveway ends and the yard begins.

Without that manual (or a lot of Googling), I may never have figured it out. Seriously, it wasn’t obvious.

Funny thing, the same concept came up with a couple of clients just today.

They each had a question about functional and well-designed systems that we created together many months or years ago, which for some reason were acting in surprising ways.

For one of them, it was easy enough to consult the Google Doc that contained a detailed explanation of how it all worked, and why it worked that way. So we could see that the system is working exactly as designed (though it may need some changes now, in light of newer developments in their organizational policies).

The other was more of a mystery.

It was built several years ago, and though we had several discussions and training sessions at the time to ensure the client understood it all, there was very little in the way of written documentation.

I had to go back and literally read through the code to understand what was going on.

Not a major problem, but not the most efficient use of time either.

Here's the thing:

When you buy a hammer, it doesn't come with a user's manual. Because it doesn't need one.

But just about anything with moving parts does.

So does customized software.
Or complex configurations.
Or any part of a system that takes more than a couple of words to explain.

Sure, it's wonderful when it's fresh and new and everybody’s happy that it works as needed.

But when questions come up later, you'll be glad that you wrote down how and why it does what it does, and filed that away somewhere for easy reference later.

All the best,
A.