The main goal of documentation is to exist. And what happens most often is that it doesn't.
Accordingly, everyone wishes it existed, but there's no one inside the company who properly makes it happen.
The contradiction above has caused me constant tension throughout my twenty years as an entrepreneur and programmer, and this whole problem area has always hung over me like the Sword of Damocles.
Once I had employees, the timid wish of "it would be nice if you wrote some documentation" kept turning into a firm request, and eventually faded into hopeless waiting. In the end, every manager has their own pet peeves — what else would they give up if not documentation, right? Wrong.
My experience is that every proposal has to include a promise that you'll write documentation. Then nobody reads it. In the end, you can write whatever you want — no one has ever complained to me that it's missing (maybe because it did exist) or that they don't like it. Everyone hates reading, interpreting text. Just let the code run and the report look good.
Then there's the fact that everything changes, evolves. Who's going to go back into the documentation and record the changes? Even if something was created after the first round of development, just so the invoice could get paid, chances are it will stay that way forever. Like a website that hasn't been updated in three years. People would rather delete the whole thing than burn themselves with it.
And finally, what should documentation even look like? Did someone, somewhere, at some point receive a template saying, here you go, this is the expectation, this is what it should look like? Or have you ever seen one you actually liked? Besides, the code is right there — go read it, reverse-engineer it.
What should documentation be about?
For me, the first and most important consideration when writing documentation is: if someone completely new to the topic sat down next to me, what is it that I would tell them. What's the process, who or what does what and why? There should be a flowchart. The documentation should give a picture of the relationships and connections — that alone may be enough.
At least, answering these questions is the most important content requirement. Always keep asking yourself these questions, again and again.
What skills are needed to write good documentation?
First of all, learn to touch-type. I got this step done 14 years ago by buying a CD-ROM called Gépírás 2000 (Typing 2000) and practicing with it every evening. At the same time, I'm slowly getting to the point where, by the end of the three-month probation period, anyone who can't do this is better off parting ways. It just won't work without it.
Second, you need to learn the professional vocabulary and how to construct sentences. You need to read a lot. You need to avoid filler words like "which," "that," "thing," and the like.
For example, instead of the sentence "the file gets uploaded from the warehouse into the system," it should read: "the warehouse procurement department's staff member uploads the EPS file containing the order data into the DEPO-X system's order module, under the order upload menu item, daily between five and six o'clock."
Third, just start. At first you'll sweat blood (and worse), and that state will hold on for another couple of months, but then the results will slowly start coming in.
Why shouldn't you give up on documentation?
I think this has to be part of your professional standards. I've never played the game of keeping everything in my head so I'd be harder to fire. The fair thing to do is to hand over the knowledge along with the work. No one will read it anyway, but in exchange they'll like you more, because they'll know it's there.
The second thing is when you have to take over someone else's work because they're leaving, getting sick, having a baby, or setting off on a trip around the world — the pressure is on you, the expectation is on you to solve the task. Wouldn't it be better if they had passed down to you, in written form, the answers to questions like "what's the process, who or what does what, and why"?
Finally, both the client and the supplier run enormous risks.
The client, because they can lose the supplier at any time, or the supplier can say tomorrow, well then, it'll cost twice as much.
The supplier, because if their top-notch colleague leaves (not that top-notch really, since they never wrote any documentation), then what do we do now? The question arises.
All in all, I don't understand why we take on such huge risks. Why is no one — with respect to the exceptions — able to practice this discipline at an acceptable level?
Right now I'm experimenting with video documentation. Maybe that's the future. I don't know.
But I won't give up.
