jay's old blog

this blog will be deleted soon - please visit my new blog - https://thesanguinetechtrainer.com

Development Documentation and why do it

Now that many of study nildana students are pursuing some serious, hardcore certifications, I expect many things from them. I expect them to take up mentoring of their own. I expect them to conduct workshops with minimal supervision. I expect them to program like pros and that means, I expect them to document the sky out of their code.  

A lot of times folks think that I boast about myself a lot! Like, way too much. Many imply that I probably lie a lot as well, about my abilities. Without denying or confirming that, I can be honest about some other things. For instance, as a developer I am average at best. I have the essential skills to get the job done. When given an assignment, I will ensure that the bus arrives on time, and the passengers were safe and comfortable during the journey. I may not be able to give them a thrill ride, like jumping across bridges or drive them through a herd of buffaloes or lions who are going at it like the species is going extinct.  

While my developer skills are passable at best, I make up for it by doing stuff that I am yet to see many developers do. One of those things that I strongly believe in is documentation. I have wrote about this previously, and decided to add some pointers to it.  

The nature of software is that it evolves over time, and until someone pulls the plug and says 'okay we are done with this app', there is always something that can be done with it. This is why versioning happens with software. Each version will be built, targeting a particular feature set that needs implementing. This feature set is provided to the developer, who will then go about developing it, one feature after another.  

What I have seen is, developers – the moment they are assigned – just pull out their laptops irrespective of whether their brain is ready with a rock solid solution. That means, a lot of times developers are working with half-ready solutions that don’t really go anywhere. Eventually leaving everybody involved dissatisfied and creating awkward scenarios.  

Rather, what I suggest is to start with documentation. 

Even in the world of software development, perhaps the most important tools are a pen and paper. A drawing board is also useful if the developer has access to it. When a feature (hence the problem to solve) is to be ready, best to start off by solving it with the pen and paper. Find out if said feature can be implemented. Since almost everything is actually possible in the world of software development, the real deal here the time it would take to build said feature. If a feature takes 10 hours and the available time is only 5, then that feature cannot be built. If a feature takes 10 hours and available time is 15 hours, then yes, the feature can be built.  

In fact, many forget this key step. Since they already pulled out their laptops, they will trudged on find out 10 hours later that, yeah, said feature actually needs 20 hours. At this point, they realize that this feature, given the time limitations need not be done. That means, 10 hours are now wasted.  

Once it is understood that a feature can be done at reasonable time, next comes the actual plan to make this work. Each feature will need knowledge of specific library usage, method calls, class definitions and of course the algorithm of fixing it. Some algorithms are short (hence you can simply keep them in your brain) and other times, they are complicated and you draw them out on the old faithful pen and paper. When working along, mind stored algorithms (which only apply for short stuff) are best. Your brain has already figured out the solution and drawing it down 'may' be a waste of time.  

When working in a group which is working on said feature together, algorithm drawing – short or long – needs to drawn physically. Same goes to planning out the knowledge of understanding all the necessary libraries that will be used, classes that will be used, classes that will be defined new and understand relevant code that was written by other teams. Unless each and every component is understood and all particpating members are in the clear, the actual 'coding' should not start.  

This is another area where I have ran into issues. I find that my team members don’t really want to do any of this. They think, acquiring this knowledge is a waste of time and they get ready to whip out their laptops. Remember what I said about not having a solid solution? On the contrary, I believe that knowledge is truly a battle half won. You don’t go to a battle hoping to win. Rather, you plan in advance and have a 'calculated' guess that you will either win or lose.  

After all this is done (and you have jotted everything down), you start the coding. The documentation does not stop at this point. What I do is, transfer everything that I have jotted down into an online document which includes all the notes about the flowchart (in the form of photos or scans), links to relevant libraries and code (msdn, stack overflow, forums and comments from previous code).  

Now, earlier I said that the battle is only half won with knowledge. That is very true because, despite all this planning and documentation, there are any number of things that can go wrong once you do start coding. Perhaps the earlier assumption that the class would be public is no longer valid because the other team has changed into a private. A method signature might need changing for which you need to get approval. A method could be depreciated by a new library that is required by the feature you are developing.  

Which is why, even as I code away to get the feature to work, I make notes about the code I am writing. I make a note of issues that I ran into. Obviously, my code is intersped with comments which also make their way into the document I am maintaining. Finally, when the code is completed and the feature is successfully added, I have a fully developed documentation that compliments my efforts.  

Of course, the 'documentation' is an overhead. It consumes time. 

Developers, especially experience developers (those who like to whip out their laptops in a hurry), don’t like to do this. They want to be 'fast'! Perhaps, it gives them a sense of accomplishment when they add a requested feature in less than a minute even if the project manager has allocated two days (16 hours) for it. 

For me though, it is about trust, more than anything else. If a project manager (who we have to assume is competent) has given 2 days to do something, it probably needs that much time.  

Then, there is the fact that this documentation will help me in the future. A lot of times, it just so happens that future features require similar thinking and similar code and similar libraries. When a new feature request arrives, I need not 'rack my brain'. I need not spend time thinking really hard (while wearing a big hat and growing a thick beard) trying to remember what I did one week, or one month of even a year ago. I simply do a search (all documentation is stored online and hence indexed and searchable) and open up the documentation. In less than ten minutes, my mind is refreshed and my 'prep' time for the new feature implementation comes down from an entire day to less than a few minutes.  

As time goes and more features are built, the documentation also grows. With each documentation, the 'prep' time keeps going less. Eventually, you would reach a point where almost everything that is relevant to the job is documented and building new features become an actual walk in the park.  

As always, I believe in the long game when it comes to software development. You code, not for today, but for ten years from now. Take your time, play around until you are in the groove, be sure of your plans and only start doing when you are sure that you have a solid solution in your hand.   

Follow me on twitter, facebook and instagram for more updates. Thanks!

Comments are closed