What level of formalism should I use for requirements and specifications? This is a very common question I get, and, frankly, the answer might be disappointing, as there is no magical recipe or universal formalism that works.
Working on many projects of different sizes, I was exposed to almost any level of formalism for software specifications from none to extreme formalism. UML was often tried on the formal side, as its name bears a universal objective, but it clearly failed on all projects that I have seen which thought it would be the ultimate solution. It is too complex for end-users, which means developers cannot count on user validation as a real commitment. In best cases, it provided some documentation capabilities for technical people.
This said, should we give up writing specifications and stick to an oral tradition when it has worked in the past? Probably not. This can work for very small projects when there is a clear stakeholder for users and a unique developer, but it does not scale well. For projects that need more cooperation between people, it is critical to have some specification documentation, so the key design decisions are in a centralized document, and requirement change can then get tracked. It is of course even more necessary when teams are distant.
A simple documentation process
If there is a good reason to write specifications, then the reason should apply to maintaining up-to-date specifications. It is like writing software: if you don’t have a maintenance strategy, don’t develop software. So the formalism should be adjusted in a way that allows easy maintenance of the document when change will occur (and for sure it will). This is why it is valuable to have a process and document which really concentrates on the key elements necessary to develop, and not more.
In my view, three elements are necessary:
· As a business analyst, you should write a textual description of what the software does, and a clear explanation of its objective. If you cannot describe in "textual mode" what the program should do, then you are not clear enough about what you expect.
· The business analyst should include in the document the visual representations of what the user interface will look like. It is not just an option, as very often, the user will "see" the user interface as being the software.
· The business analyst should gather an exhaustive list of business rules and behaviors, including what should happen in limit cases, as the developer should not be creative on these points. I noticed that a lot of implicit "rule-related" elements are sometimes forgotten, as they seem obvious or natural to business users. But they cannot be guessed by developers, and it often causes much trouble at application delivery.
If you make the effort to integrate those 3 pieces into one document describing the software to be developed, then most of your risk is managed and under control. Beyond the content itself, the fact that information is centralized in a single document gives a global view and bears a lot of value.
A simple example applied to our registration process on the Web
To make things concrete for our readers, here is how we articulate specifications for our web page registration.
Textual part:
A web page allows users to register on our web site. When clicking on the relevant link, the user gets a form with fields to complete, some of them being mandatory. Once completed, the record is created in the database with an inactive status and an email including an activation link is sent to him. A page with an explanation is displayed. When clicking on the activation link, the registered user is set as active, his free CodeFluent Entities license created and a confirmation page is displayed.
User interface part:
Below is how the entry form looks like.
Business rules:
1. The fields with a star before the label are mandatory
2. The email should be a string including an @ and a . after it. (another option could be to include here a regular expression)
3. The two entered passwords should match
4. The username should not already exist in the database
5. The country is selected in a dropdown list built using Windows standard country list
6. At registration, the customer can choose between Express and Personal license
7. The license key is created after click on the activation link by calling a web service on our licensing system
Mistakes observed on the field
It might also be worth noting the common mistakes or things that I have seen as not working about writing specifications:
· Using excessive formalism with a language that is hard to understand for users,
· Forgetting about visual representation of user interfaces,
· Not being precise and exhaustive about the description of business rules,
· Splitting specifications into a set of numerous separated documents.
As always, feel free to comment or complete with your own observations.
Daniel COHEN-ZARDI, CEO
