Publication Date: 4/24/2009 12:58:12 PM
Everyone hates documentation. It is either boring or it doesn’t answer provide the needed answers. Many programmers agree that documentation is critical when they are taking over a project for someone else, and think it is completely unimportant when they need to create it themselves.
So as a customer: what documentation should you expect or require from your programmer?
Every situation is different, but here are some documents you may want to consider requesting:
This is the specification that was (usually) created before the programming began. It can include functional specifications, wireframes, screen mockups, user stores, UML diagrams, screen to database field mappings, etc. The good news about system design is that it can really help the developer understand how the application started. The bad news is that over time, it can get pretty stale unless someone is keeping it up to date.
In most cases I work with my customer to create a system design before programming begins, but this is not always the case. If a system design is provided as part of the project, make sure you request the most current version when the project is completed.
This is “what if I’m hit by a bus” document. Its purpose is to allow another programmer to set up the application on their system with a minimum amount of pain. It should include:
A good programmer knows that this documentation can smooth the transition to another programmer, and that it is your right to want to minimize vendor lock-in. Don’t be uncomfortable asking for this documentation.
Every project involves decisions. Some decisions are obvious (we built a web app because we needed to give external users access to the data) and some are arbitrary (we wrote it in PHP because that’s what the programmer knows). Documentation that covers the “why” for the important decisions can help the next developer understand how the project evolved and can help them to not cover the same territory. For example:
Some of these “why’s” may belong in the code comments as well.
When programmers are asked for documentation, sometimes they use a generator to create a list of all the functions and subroutines in the system, with a description of each. While this can be relatively easy to generate, I’ve found its usefulness to be fairly limited. As a programmer, I rarely look at this type of documentation.
Depending on the application, this can add a lot of value to an application. It can provide that polish that takes the application to a professional level.
However, many programmers have trouble thinking like an end user. (Remember, many programmers are aliens.) And creating this type of documentation can be expensive. So before you decide that the programmer should provide end user docs, ask if this is a service they provide. And ask to see examples of other user documentation they have created. Then decide if it makes sense for the programmer to write end user documentation or if it should be created by someone else.
Creating documentation takes time. Think about what kind of documentation you want before the project begins and make it clear to the programmer what you are expecting. That way it can be included in their bid.
Think like a geek
Your URL (optional):
Type the code shown
Top 5 Programmers to Avoid
What everyone should know about bugs
How to tell if an estimate sucks
The Secret to Building a Crappy User Interface
The Problem with Selecting the Lowest Bidder
5 Ways to Control Software Development Costs
Avonelle is a rare IT professional who can communicate with business users on a level they can understand, and who can recommend creative technical solutions that are in line with the business goals and the business budget. Avonelle is conscientious not only about meeting deadlines, but also exceeding her customers expectations around quality software while providing superior customer service. Avonelle is an inspiration to me.
Valerie Vogt, Director of IT Advisory Services @ Inetium
Copyright © 2013 Avonelle Lovhaug. All Rights Reserved.
Sitefinity ASP.NET CMS