A tricky part of the application development process is creating a software specification. The requirements do not tend to pose the same problems as specs. Unfortunately, there is too often a spill over into an attempt to define implementation or place restrictions too early. Nevertheless, a software specification is essential to a successful project so let’s look at how to put one together.
Start From Requirements
When you start out focused on the requirements, it is easier to avoid getting into implementation details. Think of taking one step deeper and moving on rather than going too far into detail. The specifications should be a natural step from requirements. Therefore, those are your outline. With each element, you will have a series of questions to answer that can help with the spec.
- What does this look like for the user?
- What are the input and results?
- Are there technical details that need to be provided? (size, color, type, etc.)
- What can go wrong?
- How does this work?
Each requirement will have a different context for these questions. Thus, screens will have vastly different answers from stored data which will be different from application interfaces. The goal is to add a stronger description to your requirements. Therefore, that should be underlying the answers to these questions.
Specifying Screens or Pages
Data and functions are more straightforward to define for me than GUI requirements such as forms and screens. There is a way to approach detailing them that stops short of implementation. The trick is that sometimes the exact control is needed as part of the requirements. However, the precise implementation of the control is often not part of the requirements. When dealing with graphical containers like screens, I find it useful to use these questions as a guide.
- What is the general structure? (one section, tabs, multiple parts, grid-based, flow layout, etc.)
- What values are displayed or captured?
- How does the user proceed to the next step or navigate away from this page?
- What sort of interactive pieces are needed? (pop-ups, filters, hide/show values)
- Is this view the same for all users or does security need to be taken into account?
- What validations are required for the input?
- Are there messages that are shown to the user?
The answers to these questions provide excellent guidelines for a specification.
Software Specification is Not Implementation
It is easy for a developer to think about how they will implement a requirement as part of creating the specification. That can cause you to design your way into a corner. Instead, you can either use non-developers to create the specification or review the document along the way to pull out references to implementation details. Fortunately, these can be easy to spot and include language references, structure references, and language syntax for terms or types. An example of the last would be referring to a value as being a String or varchar instead of calling it alphanumeric or text.
User controls have a similar tendency towards implementation details. For example, You may have a requirement that a user selects a value from 1 to 10. Nevertheless, this does not have to be a slider or dropdown with the values 1 through 10 in the list. Avoid creating requirements as you build the software specification.
There are volumes written on how to write a software specification. This alone should hint at the importance of getting this step right. However, this is another area of development where experience and practice are the best teachers.
