Hello reader, welcome back, it’s been a while.
Today I have been thinking about the documentation topic. For me, it is a very hot topic. In the deepest shity moments everyone is saying how good it would have been to have some documentation. Everything lasts until the problem at hand is “hot-fixed” (as this would ever exist). As soon as the problem is patched and the project is printing money again the voices change to “buhaha, let’s reduce the development time, cut the costs, fuck the documentation”.
I do wonder, still, after a couple of years, how come, exactly the ones that have no skill nor knowledge in approaching the crysis reach this conclusion. You, the hopeless ones should be advocating for proper documentation because it is your CMA ticket in case of emergencies. It is the only proper piece of information you can rely on and share with a team member later in the night from whom you are expecting the problem to be solved.
There is also the management aspect. The business wants things that will be invented tomorrow done yesterday.
Maybe is the development team’s fault. We taught them to be this way. All they have to do is ask and stamp, we will fix it.
Maybe is the product owner’s fault. With all this agile shenanigan we are not able to tie our shoes properly anymore.
Maybe, maybe, maybe… maybe is nobody’s fault. I’d go for this route. We are all equally guilty for not paying attention to everyone’s need in order to perform better. We all look at that stupid burn down chart and cherish like some teenagers when we go below the line.
I see a solution though. Many years ago, programming has evolved from procedural to object oriented in order to do more in the same amount of time.
I would say that this is a good solution for the documentation. All we need is a platform which allows us to include pieces of documentation from one page to another.
This is necessary because each piece of documentation for each feature is written only once and maintained only once. I use the excerpt macro a lot at work and it is just the tool needed for the job.
Imagine that you write the documentation for the login feature with all the required tests. The same button is used on the pages 1,3,4,10. All you need to do is use excerpt and done. All the tests and relevant information follow the reader everywhere.
I don’t think I can explain you long enough why this macro or something similar is a must.
Now that we have the tool and the plan, next time I will propose the kind of information that should be written in the first steps of the documentation process. Don’t forget, everyone wants it fast. In order to deliver this we must be able to stop and start in the spare time without having to read again where we have left our train of thoughts.
A while ago I have read that developing happens when the developer writes something new. When the old piece of code has to be read and interpreted it is called maintenance. The world does not have time for that.
I hope this will help you make an idea how the documentation should be written. In order to get a bigger picture on how this help you can read My friend is not insane.
More to this topic soon.