How (not) to document?

Documentation

The main purpose of documentation is to be. And the most common is not to have one.

Accordingly, everyone wants one, but there is no one in the company who can do it properly.

The above contradiction has been a constant source of tension for me throughout my twenty years as an entrepreneur and programmer, and this whole issue has always The sword of Damocles hanging over me. 

By the time I was an employee, the timid request "it would be nice if you wrote a doxie" kept turning into a firm request and finally into a desperate wait. After all, every manager has his or her rubber stamps, what else to give up but documentation, right? No.

My experience is that all bids should include that you write documentation. Then no one reads it. After all, you can write anything you want, I've never had anyone tell me they didn't have one (maybe because they did) or didn't like it. Everyone hates reading, interpreting text. Just keep the code running and the reporting good. 

And then there is the fact that everything changes and evolves. Who is going to translate the changes in the doctrine? If anything was done after the first development, just to pay for it, it will probably stay that way forever. Like a website that hasn't been updated in three years. I would rather delete the whole thing instead of burning themselves with it.

Finally, what should the documentation look like? Has anyone, anywhere, ever been given a sample that, here's the expectation, this is what it should look like? Or have you ever seen one that you liked? And there's the code anyway, read it, decipher it.

 

What should the documentation be about?

For me, the first and most important aspect of writing a documentary is that if someone completely new to the subject sits down with me, what I would tell him. What is the process, who or what is doing what and why? Make a flow chart. Documentation give an idea of the context, that's probably enough. 

At least, answering these questions is the most important content requirement. Always ask yourself these questions again and again.

What skills are needed to write good documentation?

First of all learn to type blind. I took this step 14 years ago by buying a CD-ROM called Typing 2000 and practising it every evening. However, I am slowly getting to the point where, by the end of the three-month trial period, anyone who cannot do this is best said goodbye. It won't work without it.

Second time learn professional language and sentence structure. You have to read a lot. Avoid what, who, which, thing and similar filler words. 

For example, instead of the sentence "the file is uploaded from the warehouse to the system", it should read "the EPS file containing the order data is uploaded by the warehouse purchasing department staff to the DEPO-X system order module under the menu item upload orders between five and six hours a day".

Start a third time. At first you will sweat blood (pee), then it will last for a couple of months but then you will slowly start to see results.

Why not give up documentation?

I think this is the part of your professionalism must be. I've never gambled on having it all in my head and at least it makes it harder to get fired. The fair thing to do is you pass on knowledge as you work. They won't read it anyway, but they will love you more because they will know that you exist. 

The second thing is, if you have to take over someone else's job because they're going away, getting ill, having a baby or going on a trip around the world, there's pressure, expectation, to get the job done. Wouldn't it be better if you were handed the answers to the "what is the process, who or what is doing what and why are they doing it" type questions in a fixed form?

Finally, the customer and the supplier are also running huge risks. 

The customer because he can lose the supplier at any time, or the supplier says from tomorrow, that it should be twice as much. 

The supplier because if his top super colleague leaves (not so top super because he didn't write a doc), what should he do now? The question arises.

Overall, I don't understand why we are taking such risks. Why is no one - with respect to the exception - able to do this genre at an acceptable level?

I am now in the with video documentation I'm experimenting. Maybe this will be the future. I don't know. 

But I will not give up.

Sharing:

Discover how much more efficient it is to work with a single integrated system!

ADVICE

30-minute free consultation

Book an appointment for a free 30-minute consultation, where we will give you a deeper insight into how we can create a customized integrated system for you in less than 10 weeks!

en_USEN