Sep 8, 2015

The importance of documentation

Any IT worker has most probably been in the situation once, twice, too many times to care to count.



You have a software you need to implement and use - but how does it work? What does it do? What are the features? "Oh, you know, it was built according to your specification.""Yeah, but...?" "Oh, the person who coded it, doesn't work for us anymore."

You need to set up a test environment similar to the production. Or duplicate the production. But what features, what services need to be activated and configured? "Oh, you know, the usual, just next-next-next, we don't have anything special there. Just activate everything." "???" "Yeah, well, I don't know, it was originally set up by this company X, but the contracr expired alreaydy, and besides I think they don't exist anymore. That's why we need you, to figure this out."

You need to add some features to a custom made application. You get the source code, you can run it (but of course it can't use half of the features in your test environment), but how was it built? You look at the source code and use hours to try to figure out the noncommented code to understand how to implement your own and end up wishing you could just code the whole damned thing yourself from the scratch. "Documentation? No, we didn't get any documentation. No, the person who coded it, oh, I don't even know..."

Getting my drift? Documentation! That boring as hell job, that makes you disposable when you're actually NOT the only one who can figure it out. The boring as hell job, that tends to remain undone, when the project budjet was already used up and "not in this life am I gonna do that for free!" The boring as hell job, that nobody really wants to do, but everybody curse about when it's not done and you'd need it.

What happens when there's no documentation? Stonehenge happens, that's what. Here's this fabulous construction, somewhat fallen apart, but what did it do? What was it's purpose. Tourists flock around to gawk at it, but that was hardly its original purpose! Not that anybody probably would put it back together; it's more valuable as it is, untampered, than back in its original configuration.

Yet, without any documentation humankind had no idea that the mysterious thing we've been gawking at for so long, without understanding what we've been looking at, is actually only a fragment of something much bigger!

Pic from the aticle mentioned above

That's what you get without documentation. No idea what you're looking at and not even knowing you're missing the biggest part. People, document your work unlessyou want it to end up a mystery like Stonehenge!

No comments:

Post a Comment