Friday, March 11, 2005

Document! Document! Document! (on paper)

Part I
As a programmer I've said it myself, "I don't have time to document my code."

What we are really saying is "I did a poor job on this project."

Programming should begin with documentation. The IEEE has all sorts of documentation procedures and best practices (wow! An excellent short article by IBM). My first documentation happens when I meet with my client for the first time. I take notes and lots of them. I like to put each client/project into its own Mead Marble Composition Note Book. These are inexpensive, the pages don't tear out, notes are storied chronologically, they fit neatly in a file cabinet and stand out amongst the junk on your desk. I also keep a file folder with the note book for all loose papers and printouts.

The first note I collect from the client is contact information. This is documentation! If another programmer picks up your project that programmer needs to know who to contact. Imagine this scenerio:

President of the company Alice assigns manager Sue to hire Superior Internet Designs to build a piece of software. SIDesigns assigns programmer Joe to the job. Programmer Joe gets hit by a bus. SIDesigns offers to put programmer Beth on the job but president Alice decides her employees are all too busy at the time and delays the project. Six months later president Alice contacts SIDesigns to say she has assigned manager George to see this project through and programmer Beth is placed on the project.
Example 1
Without documentation George and Beth would effectively be starting over. If the contact information had been documented, Beth would know to ask if manager Sue was available to bring them up to speed on the project.

Back to my initial meeting with a client. After recording contact information, I let my client describe their needs. I try hard to listen and avoid talking. At this point I am trying to learn what they want done and if I contribute too many "what ifs" or "you could do" statements then I am leading them and we will likely develop a product that doesn't match their initial expectations. While the client talks I am documenting. In my notebook I record as much as I can of what the client says. These notes will later be refined into a formal requirements document. Ludwig Consulting Services, LLC has some excellent document templates. Their documentation is closer to the level of documentation used on government projects. Unless your have an exoberant budget for documentation I recommend you use the concepts and simplify the documentation.

After the client is done describing their needs I will ask some pointed questions and record those answers in my notebook. When the meeting is done I will immediately transcribe my notes into an electronic form creating a specification document and requirements document.

All documentation must go through a client review!

We will continue in another post and discuss recording assumptions, data diagrams and data dictionaries.


djuggler's personal blog is Reality Me and consults as Superior Internet Designs.


Posted by: djuggler | 10:02 PM |