No spec is the same but what remains the same is the art of writing the spec.
I don’t know if you get the feeling “where do I start from” when you have been approached to write a spec. Usually, the customer has a vague idea of what they want and explain it to you in what seems like a blurb of a seemingly excellent idea. You jot down notes madly during your initial conversation with the customer and still think “where the heck do I start from?”…
The pointers detailed in this blog have guided me through producing detailed specs which have contained “just enough” information sufficient for the right audience. I hope this will prove useful pointers…..
Firstly, I would say, consider the audience of your spec. By audience, I mean the architects that will design solutions based on the requirements in the spec, the developers that will need to understand the requirements and develop the application, the customer that will need to understand the spec from a layman's perspective and see straight away that the spec addresses all their needs, the tester that will need to understand the acceptance criteria and functionality required in order to test the developed application orthe business users who will benefit from the application.
You might instantly think, how can one spec cater for all these people…my answer will be; certainly do-able if you capture “enough” of the right information.
Next find out the key stakeholders. These may be the same people as the audience but sometimes you may have project sponsors, senior management, marketing staff or business users interested in the spec. So in this case, you are going to want to talk to these stakeholders to get their expectations\requirements while bearing in mind that its the known audience [architects, developers etc] that will use the information in the spec. More often than not, the people involved in the requirements gathering phase will be determined by the customer although you may request participation of people you see fit to contribute.
Arrange a meeting with the most knowledgeable person about the proposed application \ product owner. The aim of this meeting is to get a picture of what is intended. This person may provide you with a set of business cases, maybe financial or business implications as well. At this point, you would ask general questions about what the problem is, what the current solution is, what the vision of the project is, who would be involved, what the budget is and who the intended users of the system will be.
By now you would have a vague list of functionality required by the system, group functionality together then kick start the requirements gathering process. For each functionality jot down the requirements. Already your table of content is beginning to take shape. For each requirement, ask the 6 W’s [Who, What, Why, Where, When , How] you’d be amazed by how many questions you would gather together. Imagine a scenario where the customer says, “I would like to send out notification when errors occur”. It sounds straight forward initially but who would the notifications be sent to, what is the content of the notification, what errors should trigger off notifications, how will the notification be sent, when should it be sent, where would the notifications get generated …and the list goes on. Answers to these questions may even lead into discussions about flows. From the notification being sent, the user may respond and expect an action which will only happen if….The picture will have started forming.
By now you should have anoverview of the application required. You would also have a few business requirements and an understanding of any current systems which may exist. As with any application, data must flow between 2 end points. Subconsciously, scenarios would have discussed data flows for example the user will be authenticated with the server before any of the configuration data is saved. Already, there is a concept of authentication data flowing to the server from the client. There is also configuration data being mentioned.
Start the spec by summarizing requirements into an overview section. Diagrams are always useful and you don’t have to be a UML guru to put one together. If your diagram effectively paints the picture then its good enough … you may have something similar to
Already, you have catered for the marketing department who more often than not don’t want to get bugged down in the detail. They just need enough information to sell it. Sometimes the business users just look at the table of content and the screen mockups to determine functionality coverage. Instantly, you’ve satisfied these sort of customers. In addition to this overview, you’d have started building a table of content which will may now look like:
1 Document Control
1.1 Document Location
1.2 Revision History
2 Background
3 Current Solution Overview
4 High Level Requirements Summary
5 Business Requirements
6 Use case models
7 Functionality 1
7.1 Requirement 1
7.2 Requirement 2
7.3 Requirement 3
8 Functionality 8
8.1 Requirement 1
8.2 Requirement 2
8.3 Requirement 3
Get the customer to review what you have so far to ensure you are on the same page.
Next arrange workshops with like-minded stakeholders i.e. techies together, business users together. It will be your job to bring these varying perspectives into a consolidated spec. By now you would have a list of questions which you want answers to. Ask the relevant questions to the right disciplines. Sometimes you may find you are asking the same questions in different meetings. It doesn’t matter provided you are getting a clearer picture of the requirements. At the start of the workshops let everyone talk, listen attentively, let them express what issues they are expecting the application to resolve, ask them about the current system… they may answer your questions and new ones may be raised. Encourage discussions of scenarios and user stories. Make note of as much as you can. Sometimes you may need to provide a gap analysis, this is the point where most of the information you’ll need would be gathered. Always remember that during this process there will always be industry specific terminology being used here and there. Make a note of these, already your glossary is building up.
From the information gathered at the workshops, you can start fleshing out functionality without loosing sight of the audience. With every line you write ask yourself what information you are trying to present, think outside the box, suggest other ways of doing things [maybe include this as comments which the customer may respond to] then decide the best way to represent it. For example, a tester will like to see a flow chart which represent exceptional flows. A developer will like to see field lengths and validation required during data capture. An architect would like to know if external servers will cater for certain functionality. A business user will like to see a use case diagram showing what users can do with the application. Where possible mock screens up. An excellent site a colleague told me about recently is http://www.balsamiq.com. Always think things through and where possible link functionality to business cases. Relate functionality where appropriate for example, if you imagine a set of configuration data which will be used in various parts of an application. Consider when the configuration data changes consider where the updates will need to be applied, what will be affected, should notification be sent, will this cause loss of data and a lot more questions should start springing to mind.
A lot of times Non functional requirements are shoved to the side until its too late to be considered. Every spec must contain a Non functional requirements section. Depending on the nature of the application, these would be requirements like performance, memory usage or requirements relating to graphical user interface constraints.
By now you should have a spec that has grown considerably from a summary to a detailed spec.
At this point, I’d say your spec is ready for review. Take a break from it, then come back to it with fresh eyes. Its difficult to spot errors or missing information from a document you wrote, and have been looking at for days. Get other people to review it. Incorporate feedback and send an initial draft to the customer. Its likely you’d get feedback like “Oh I didn’t envisage this happening this way” in which case, you have more requirements gathering to do and more writing. The spec might go through a couple of review cycles but not too many otherwise, there is probably something wrong. Either you are not accurately representing the information you’ve been given or the customer is not giving you accurate information. This will need to be addressed otherwise you’d find yourself in an endless review cycle.
Create a requirements catalogue. the requirements should be finalized by this point. You can do this as a spreadsheet with each sheet representing each piece of functionality and each entry in the sheet representing each requirements. The catalogue, at the minimum must contain the following information:
Project/System |
the name of the application \ project |
| Author | your name |
| Date | the date you start writing the catalogue |
| Version | the version of the catalogue e.g. 0.1, 0.2 for drafts and 1.0 for live versions |
| Spec version | the version of the functional spec the catalogue relates to |
| Requirement ID | a consistent ID for the requirement. I would say abbreviate the functionality name and add a number e.g SavePref1 |
| Requirement name | the name of the requirement e.g. Save User preferences
|
| Priority | MoSCoW [Must have, Should have, Could have, Want to \Nice to have] |
| Spec reference | Reference to the chapter\section of the spec |
| Functional Requirement | a description of the requirement. Usually an extract of the spec
|
| Description | a more detailed description of the requirement and bullet points of what is needed to achieve the requirement. e.g. Request user preferences from server, report conflicts, save to server, notify all users of changes |
| Non-Functional Requirement | a description of any associated non functional requirements e.g. save must be asynchronous |
| Description | a more detailed description of the requirement |
| Estimate | An estimate of development efforts in points or time |
| Additional info | |
| Comments | |
You may ask, what's the point in this when there is already a spec? Firstly as the person that wrote the spec, this exercise should not take long [I’d say a couple of hours depending on the complexity of the functionality]. A project manager will definitely instantly see value in a summarized list of the requirements detailing development efforts \ estimates. A customer may decide at this point to de-scope time demanding requirements which bring little business value. A tester may use this to kick start test case writing lastly the solution provider will definitely want to provide a cost estimate which is as accurate as possible so that the project doesn’t go over budget.
At the end of the review cycle, you should be confident that your customer is happy with the spec and is ready to sign it off!.