No matter how small a project is, some type of specification should be created. A good specification makes certain that all parties involved in a project know what the end result is going to be. Typically it takes longer to get the specifications of a project than to create/code the project. And that's a good thing. Proper planning upfront saves time in the long run.
A specification may be as simple as a drawing on a white-board or as complex as a multi-page document that includes mock-ups, uml models, database design, etc. One thing I've learned over multiple years of development is that you can't go too far when gathering specifications. The more questions you ask and planning you do the better your application will be.
The key areas and questions I concentrate on when gathering specifications are:
- The application itself: What is it for? What does it have to do?
- The schedule: When do parts of the application need to be completed by?
- Who will use the applicaton: Who are the administrators? Are there different "levels" (admin, non-admin, etc.) of users?
- The Metrics: How will success or failure be measured?
- Are there any precedents: Do any similar applications already exist?
- Key Personnel: Identify the stakeholders, decision makers, workers, and anyone else whose input will be necessary to answer questions and complete the application.
- Various specification models: drawings and programming designs of how the application will look and work.
I keep my specification file right in Microsoft One Note as a template. If you don't currently use One Note please read my post about why you should: Microsoft One Note Makes Me a Better Programmer One Note allows me to keep excel spreadsheet and visio files right in my template. If you are using One Note you may download a copy of the specification I use here: One Note Project Specification Download If you don't use one note you may download this pdf file of my specification document without the visio files and excel spreadsheet: Specification.pdf
For the schedule I use the same excel spreadsheet I posted about earlier here: Project Planning
Here are some examples of the types of modeling I typically do for a project:
A UML Use Case:
One of the most important things in a specification are mockups of what the GUI will be like. I use Visio to create the mockups or, if time permits, I'll even create the "real" thing in Visual Studio but without the business logic, just the design. Creating the real thing to show stakeholders gives them the feeling that the project is moving ahead quickly and saves time in the long run. I like to stress to them that the interactive mockup doesn't include any real programming and the hard parts remain to be completed:
Finally I use Visio to model the database and classes for the application:
Programmers have an easier time imagining a finished application and the processes involved than people in other departments of a business. But it's the stakeholders in the business who know the nuances of their processes and they are the people who will be using the application. It's therefore very important to have a systematic way of making certain that all questions have been asked and business processes uncovered. The more GUI designs that can be shown to the stakeholders the better, in order to help them imagine how the final application will work for them.