Monday is Documentation Day
People around the world have run ‘Documentation Days’ to encourage greater levels of documentation in projects. I find I myself am also equally at fault for not documenting enough and not documenting well (to my standards that is).
But as my open source project gets more and more usage, I find myself spending more and more time documenting… something I should have done properly from the start.
So why is this such an inherent problem in our industry? Why is documentation such an afterthought?
Workplace Documentation
How many times have you been hired to a job and immediately asked for documentation so you could get up to speed only to find they had NONE? No ERDs, No flow diagrams, no Javadocs … nothing!
This is not uncommon. In fact, this is the norm. And we have come to accept this.
But this should not be the case.
Why Should Management Allow A FULL Work Day?
No one does it during the day and the answer is always ‘when you have time’ and the developer justifies it as ‘if they aren’t slotting time for it then I don’t have the time… which often is true.
But what is the return to management? Why do this?
- Fewer Bugs/faster testing : By having good documentation, it enables everyone to better understand the IO, the call flow, the data, naming standards, etc and as a result their will be fewer bugs and the bugs there are will be found faster. On average it would cut 30% off your bug fixing time per developer/tester.
- Faster Onboarding : Good documentation makes it easier to onboard someone. Rather than hiring a developer and trying to onboard them over a month, with proper documentation, it would only 1–2 weeks. This would decrease the time it takes to get a new developer up and running by 2–3 weeks thus increasing your departments output faster.
All of these are direct savings to your monthly budget
Least Productive Time of The Week
According to Github statistics, there are two workdays where the least amount of work happens: monday and friday… and this is mainly for psychological reasons
On monday, people are getting back from a weekend and are still trying to get back on track and get organized.
On friday, people are checking out, leaving early, etc. This is the end of a long workweek and they are emotionally, mentally and physically tired.
Ideally, monday is the best time to do documentation because it will help people get back on track and even help with tracking down bugs for the week; the process of documentation is extraordinarily helpful in pinpointing bugs and issues because it forces the user to go through analysis during the process of documentation.
Why do we need this?
Having solid documentation for your projects helps with:
- onboarding of new developers
- new client adoption of your tools
- easier integration with external tools
- easier adoption of your tools
Without said documentation, no one will ever adopt or use your tools and if they do, they will struggle and even may drop them because of they difficulties in using, adopting and integrating with them.
One day a week (your least productive day), is not much to spare to make sure that you have:
- tutorials
- installation/configuration files
- ERD’s, call flow diagrams, etc
- javadocs
I plan to start doing this myself on a regular basis and hope that a community at large adopts policies similar to this. For those doubting my level of commitment, don’t let it be said I don’t practice what I preach; I have already begun and made started making good progress:
Now you guys all catch up! :)
Note: In the time I have started my new found ‘documentation quest’, I have already found 3 bugs… just from documenting. I expect to find several more and clean them up and be able to get a new release out. In some ways, I find proper documentation jis better than testing because I would have never known to test for some of these things.
