“Most of the software systems in Kenya do not live long past their creators, because we do not document our work/code” lamented one of my client (who became my a close friend). I had just handed in a complete system with no documentation at all, save for the code comments that were written by the author of the framework, the developer who was to takeover the code-base was not in this meeting.

Documents stack from www.techbeacon.com

As expected, this was one of the projects that gave me a hard time, I was always fixing/patching the code, HELL! at one point I had to do live updates to the production code (like directly from terminal to server files… had to stress). The developer who had inherited the code base was really getting on my nerves, he would always come to my place to talk through the code (the fool discovered where I lived). Completely tired, I sat in one Friday night and documented the entire system.

This experience thought me a very important lesson, document your code!! I decided to publish these post today just to remind myself, because I began making the same mistake AGAIN. In today's development shops, new builds are shipped in short cycles, to ensure software systems can be release at any time. This approach tempts many developers to sideline documenting their work till the elusive v2.0 or v3.0 or whatever version is your next major release. This should not be allowed to happen, lets document through the process

How, it can be hard work, but here’s the trick, you don’t have to document more than a page at times; For small changes between versions can be well catered for with a change log doc, write clear, concise and consistent commit messages (more on this), honestly, I find myself referring to them when documenting a client handover doc, checkout the existing documentation tools & frameworks i.e. RAML , Swagger, et cetera. These tools makes it possible to automatically generate a clean documentation from your code. Finally, a well illustrated UML diagrams and DB schema go along way to help others understand the system architecture, be nice and include one in the appendices.

Remember we set out to write these documents for the purpose of our system longevity, for making the collaboration between developers even easier. So Friends, Don’t Let The Rush Kill System Documentation.

Friends

*I am interested to hear your feedback.