In the past few years, I’ve worked with dozens of people on a variety of different projects, within a number of areas that couldn’t be more different. I got to know a lot of high-qualified folks with a great knowledge on lots of technical topics, through that time. Those usually introduced themselves as IT professionals — but they weren’t. They were hackers. Linux hackers. Code hackers. All kind of hackers. Intelligent guys with great ideas and lots of experience. But still no IT professionals. Why?
Let me go into greater detail so everyone will understand the context: When working in the IT area, you face problems every day. Problems you can’t fix, as well as problems that are on your list of issues to be fixed. And just like anywhere else, there are different ways to fix a problem.
Whichever way you choose, it’ll introduce at least one single line of modified or newly written code, one configuration change or even a new component you might require in order to solve the issue. Due to this, fixing a problem will always affect the environment you’re working in. This change is something, you most of the time think about, execute and then tend forget. Colleagues, which work within that very same environment might not know, what has changed or maybe don’t even notice the change at all. In order to keep your colleagues informed, you probably have some sort of daily stand-up, where you mention what you changed in a few words. Or maybe you have an automated on-code-commit mailer, which sends diffs of changed code around to everyone who
doesn’t care has to care.
Whatever way of informing others it is, it’s only temporary. Nobody will remember that super-tiny but important change you mentioned in your stand-up two weeks from now. Nor will anybody remember, which of the hundreds of on-commit e-mails he received contained that change.
With such a behaviour being daily business for many companies I worked at, I’ve experienced several situations, in which code or even systems suddenly failed (e.g. after re-compiling/-starting) and no one knew why. In those cases, a good documentation is a life-saver. Not only, that it tells you who did the most recent changes, that might have caused the failure, so you could just ask this person — it also allows you to easily undo every step that was executed after the last known, working version of the code-/system-environment.
Unfortunately, in over 80% of the cases, there was no documentation at all. In some of those cases, the person that wrote the code/set up the service didn’t even work there anymore. And in the worst of all situations, this was realized just when the code/service broke down. At that point, there’s nothing one could do but start “reverse-engineering” the whole environment, in search for that one change that caused the unexpected trouble.
Those IT folks, who write code or set up systems the devil-may-care-way are no professionals. And with more knowledge they gain, they aren’t becoming more professional. On the contrary: They are becoming more dangerous. Dangerous, for every colleague with less knowledge, which has to be able to handle the super-complex and largely undocumented source-code/system-setup. And dangerous for those people who are responsible for the services to run smoothly.
This might sound harsh now, but unless you’re not documenting the right way you are no professional - you’re a hacker. You build things up that should just work, with no sustainability nor any possibilities for the “posterity” to maintain it. And the code you write or infrastructures you build might surely be brilliant, super-innovative and all that! But what good is the best approach, when there is no clear way for others to understand and reproduce it?
So please, all of you ingenious hackers: Document! If you’re not documenting your super-complex code, you’re doing it wrong! If you don’t know about ci, co or rcsdiff, you’re doing it wrong! If you don’t have at least one CHANGES.TXT within your SCM, you are doing it wrong!