Friday, March 4, 2011

DOCUMENTATION is for wimps!

Coders code, PM's write Diaries!
Within every major IT department, there really only two job functions: Coders and non-coders. The coders to which I am referring are those people who speak in binary, code in assembler, and haven't seen the sun since their first computer (aka Code Monkey). Then there is everyone else - you know - people. People who speak your language - english or better yet business, people who know technical details as well as the function of a balance sheet and people who can communicate.

WARNING: Graphic Images!
This is an actual dramatization...
of a coder writing documentation.

Verbose pseudo code
Communication is important. Correction: Communication is VERY important. Whether you are documenting a new application (preferably pre-development), meeting minutes or project status', communication is now at the core of the IT function. No longer is it adequate for coders to just code - they also need business knowledge and communication skills. Sure, a good coder might leave a few comments sprinkled throughout their code libraries, although greatly appreciated - it's not enough.

Now I have to admit - I was a code monkey in training. Yes, yes its true; however I managed to break free. As a junior coder I was stuck in a hobbit hole somewhere coding while the people around me conversed - then I discovered documentation (beam of light from the heavens and choir singing). There was a gleaming piece of hope that I followed out of my hole.

Sure the true IT grit lies with the coders (admins may argue), but you or your team can evolve to be the uber multi-lingual geek. A coder who not only writes code but communicates their intentions to the business and NO we are not writing Diaries and its not girly.  Documentation is like coding - actually think of it as "Verbose pseudo code" and the compiler is known as "Marketing".

Don't be a code monkey - document!
Writing documentation sucks - a lot. However, the benefit is that it communicates your ideas to your team, client and/or bosses. It helps you think through your approach, serves as a road map and simplifies the development process. Ever hear a coder say "Oh I must have overlooked that" in reference to a key issue created by the poorly documented change? Of course you have. With a little communication, the business need could have been outlined for the developer (not coder) and in turn, the approach could have been documented prior to development. The benefit of these steps are:
  1. Business articulates their need
  1. IT reveals the approach
  2. Everyone agrees (scope)
  3. Impact of proposed changes (scope creep) can be evaluated against project plan.
  4. New team members can get up to speed quickly

In one office, I was replacing the code monkey who decided it was time to leave. I had less than 2 weeks to extract all the knowledge he had because once he left so did the documentation.  The real reason he was leaving? I think he realized he made a mess of the systems and could not remember what any of them did. For the next few months, I spent my time stumbling through the systems and trying to document what they actually did and in the event of a failure - I did this while debugging. Sure we made mistakes - but by the time we were done - the core systems were usable.

Ramble, Ramble - Now The ROI
Good documentation saves time, money, customers and sanity. Coders have a map to follow and what the system does is clear and available - You don't have to step though the code to figure out what it does or wait for the code monkey to return from vacation to point you in the right direction. Customers will benefit from the professionalism and the reduced errors due to forgotten specifications/functionality. Finally, when you stop shooting yourself in the foot, everybody wins!

Hope this helps and not hinders!
-Project: ROI

89 BENEFITS of documentation <-- looks through - not sure there was too much documentation

No comments:

Post a Comment