Importance of Documentation for programmers


Published on

If you really want to know how important is documentation for programmers/developers then read this wonderful post.

Published in: Education, Technology
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Importance of Documentation for programmers

  1. 1. Documentation in programmingThe Independence Day began in the most thought provoking way for the members ofKolkata IT Professionals group. Yet another pertinent issue was raised by Aninda Das,which most of the programmers often overlook – not intentionally, but due to hugework pressure, lesser time at hand and crisis of resource.‚What is the importance of documentation in programming? I know many developers;start-ups/SMEs skip this process. May be they do not have the bandwidth or the clientdoes not emphasize much on it. BUT the documentation is critical. Let us discuss therelevance of documentation. After all ‚Ink is better than the best memory‛ – Chineseproverb‛, is what Aninda posted to stimulate the IT professionals to share their views,experience and knowledge.Quoting from a blog that Bibhas follows he said, ‚No matter how wonderful yourlibrary is and how intelligent its design, if youre the only one who understands it, itdoesnt do any good‛.Ulhas sharing his thoughts said, ‚Documentation is required big time in programmingfor the developers themselves as we go on coding and at times we are not able torecognize what we coded if the code gets a bit older‛. He also added that he follows a
  2. 2. certain methodology of documentation, which he himself created. ‚I do try to make thedocumentations as in comments in the scripts itself‛. The biggest problem faced bymost of the programmers is time crunch to meet the deadlines. Ulhas cited added apractical scenario which can’t be looked down up on. ‚The clients comes to the contextthey are hardly interested in the documentations for the programming instead theywant the documentation for "HOW TO USE THE FINAL PRODUCT?" as in trainingthemselves as well as their employees‛.Prashant feels that every standard software development processes must followdocumentation. He also mentioned, ‚The output of many phases of softwaredevelopment is often a document‛. A few examples of which can be ImplementationPlan, SRS/FRD, Design Document, Test Plan and Test Cases, and End UserDocumentation. Sharing some further insights to program documentation he added,‚Fellow coders who require to understand the code for maintenance/enhancement,plug-in developers who require API documentation. Programmers themselves oftenrequire design documents. There are automated tools like Doxygen which makedocumentation easy and not too much of a strain on programmers. But a certaindiscipline in the software development process is needed, otherwise programmers tendto ignore this critical aspect‛.Arjun not agreeing completely to this process feels, ‚there are different paradigm whenits comes to developer/spec documentation which does not insist on traditionaldocumentation‛. Scrum/Agile/Lean can be some perfect examples of the same whichputs more emphasis ‚on the concept of "code-as-comment" and spec documentation viaRSpec/Cucumber StoryBoard scenarios which acts as user-acceptance documentation aswell as executable spec code!‛ documentation is different for developers, PM/DeliveryManagers, Testing Groups, Marketing/Clients, and users. ‚But all these are essentialtypes of documents which are to be created in different ways as target is different andso is its use and requirement! This has to be clearly understood!‛ he concluded.Better codes for Rishav is better documentation. ‚I reject commits from my developers ifthe code is not self explanatory. Writing tests is an awesome way of havingdocumentation. We do the tests thing all the time. Simple example – there are betterways of hard-coding regular expressions into your code. Regexes are self explanatory.Use a method instead simple and easy to read. As far as other types of documentationare concerned architecture diagrams, spec docs and bug trackers are necessary‛. Theprogrammers need to document every feature in as much detail as possible.Anupam harped up on the importance of documentation. He stated, ‚Documentation iswhere your works starts. After that comes the very important part - the data flowdiagram and the database structure!!! As we all know programming is all about the
  3. 3. flow of data! Then comes the UI wire frames. Finally what I think we should createanother final doc. with everything put into right place before getting into code!‛The waterfall model of documentation, Arjun added, is slowly getting abandoned. ‚Thedays of bulky SRS or class diagram or HLD or LLD are going away fast!‛ He furthersuggested to gather knowledge on, ‚’Agile’ especially ‘Scrum methodology’, ‘Leanmethodology’ & ‘Kanban’.According to Priyankar, ‚Coding without documentation is like getting married in thetemple without getting it registered‛.Mukesh further shared his personal reasons for which he follows documentation. Withthree very practical yet simple examples he explained this further: ‚1. Collaborativedevelopment -- there is always a need for X to help Y debug his/her code.2. Maintenance -- you have written the smartest of code and you are done withdevelopment. You move to a new project, someone else wants to change a small pieceof code. If there is no documentation, a 5 min change could easily take 5 hours.3. What if you get hit by a bus? You were in the middle of solving one of the mostcomplex problems, you went out to bring food, got hit by a bus. You had solved 80% ofthe problem but now the new guy has to start afresh.‛Debashis stated the obvious need for documentation. ‚Each time a particular section ofcode is updated, documentation for the same is imperative. It helps in rollbacks ifnecessary‛.Documentation is important for others to understand your code. To make your code re-usable you must document it thoroughly. ‚Gone are the days when one coded with theintention to just make the product work, now if 40% effort goes to the actual codingthen the remaining must go on making it re-usable and well documented for futureuse‛, said Rabimba.Arun, who said is a ‚fan of quick references rather than elaborate notes‛ also added,‚We need documentation on all the aspects of the software, pre-sales and post-sales‛.To make a developer’s life easy Mukesh suggested, ‚Clean readable codes, good use ofvariable names, and code refactoring‛.The takeaways from the discussion are huge. Through the experience shared by severalindustry experts gave us some key factors of ‚What is the importance of documentationin programming‛:
  4. 4. 1. The phases of software development documentation are: Implementation Plan, SRS/FRD, Design Document, Test Plan and Test Cases, and End User Documentation 2. To recognize what we coded, if the code gets a bit older 3. Documentation is necessary for, Programmers themselves often require design documents. 4. Automated tools like Doxygen make documentation easy 5. Scrum/Agile/Lean are different paradigm of developer/spec documentation 6. For user-acceptance documentation as well as executable spec code spec documentation via RSpec/Cucumber StoryBoard scenarios can be followed 7. Documentation makes your code simple and easy to read 8. Learning ’Agile’ especially ‘Scrum methodology’, ‘Lean methodology’ & ‘Kanban’ are important for documentation these days 9. Documentation offers immense support for maintenance 10. Documentation is important for others to understand your codePost Submitted by: Sumana Chakraborty, Creative Writer & Blogger Connect with us: Facebook: , Twitter: @ITNiketan