Writing a requirement list, or functional specifications is the fist step for any software development.
If the list is incorrect or even only incomplete, the development will be difficult, as will be the customer/developer relationship.
Still, in more than 20 years in the software development field, I have seen much more often half-cooked, incomplete, incorrect, even quasi empty requirements lists than ones really usable for a good development cycle.
When the project is not really big, the customer is often tempted to ignore that step, and it's impossible to make him pay for it… But not doing a precise requirements list even in a case like that opens the door to all kinds of problems during the development.
In some cases, it will even make you loose the customer. An example?
More than ten years ago, I was contacted to develop a software doing statistical analysis on horse races (pmu). I didn't know at the time that I was in competition with other software companies and I just followed my usual methods.
After talking with the customer and doing the necessary back and forth information exchanges, I gave him a 26 pages requirements list detailing each functionality of his future software, with the necessary development times and the corresponding prices.
When he accepted my proposal, he told me why he chose me instead of one of my competitors: he got the impression that I was the only one who had understood his needs…
He even showed me their proposals : there were four of them, and they were all between one and two pages long. Two were cheaper then mine, one around my price and one more expensive.One of them was simply saying 'development of a statistical analysis on horses races software' and was giving a price.
The time spent to create the requirement list had already paid… I had the project.
This same time of course paid a second time during the development phase, the requirement list giving me the logical skeleton for the software.
Why so difficult ?
The difficulty in creating a requirement list is coming from these two facts:
- The customer doesn't know anything about developing software
- The software developer doesn't know anything (or not enough) about the customer line of work.
The immediate result of these two facts is that none of the two can create a complete and precise requirements list by himself. A close partnership is necessary for that.
Creating a requirement list must therefore be seen as an exploration and explanation phase.
Make the customer understand…
The developer first job is to make the customer understand these facts, and the second is to make him accept to invest enough time and money in this essential phase.
I'm talking about time and money, because creating a viable requirement list is a paying job (in any case, I do make customers pay for it) as soon as the project is a little complex.
I'm going to describe the method I'm using (when the customer let me do it correctly) for that phase. I perfected it during more than 30 years of development, so I can assure you that it works. It may not be full of big theory or big words, but it's a real life proven methodology.
Of course, depending on the project size, this method can be simplified (clearly, developing a software for one user is not the same as developing one that must be used by a group of 300 people). But the method described below works in all cases.
Creating a requirement list can be split in 4 main steps:
- Initial description
- Questions and answers
Creating a requirement list implies a lot of information exchanges between several players in the customer organization and the developer. These exchanges should never been done by voice (you always want to have documents to refer to). It can of course be done by snail mail, but this method means several problems:
- Very slow transmission rate (there are already enough delays due to human reaction and processing time by all the people implicated in the process)
- Copy problems (it's not necessary to copy manually each part of each mail to be able to answer it correctly)
- Different transmission time for some participants, therefore limiting the possible interactions
A chat system (like Skype) is also a bad idea: the absence of any formatting or any possibility of follow-up/organization of the information makes it a very poor solution.
For all these reasons, it is much better to use emails to communicate. The possibility to be very informal/unstructured in emails can on another hand make communications more difficult. An hybrid solution like sending attached PDF documents is therefore preferable. If the customer is not equipped with a PDF creation software, it's possible to make him install a free solution like Cute PDF (http://www.cutepdf.com) allowing to print in a PDF document from any application. Why PDF instead of word or html email? It's much more difficult to modify a PDF file (voluntarily or by mistake) and therefore it helps securing the process... Furthermore, any type of document like word means that all actors in the process must be able to open/read/write in the same format. PDF is universal enough to remove that problem.
Let's see in details each step of the process...
Phase 1: Initial description
Generally, this work should be done internally by the customer. If the project is small enough and/or if only one (or a small number of) person(s) know everything that is needed for the project, it is also possible to create this document during a discussion/meeting (in person or via teleconference).
A) The target is to create a general description of the necessary functions. By example:
1. Customers' management module including: customer form, invoicing, payment reminders management, commercial mailing...
2. Appointments management system
3. Mail management system: scan of received mail and recording of the corresponding actions taken
When some of these process are already done by hand or with another software, it is always better to include real life examples of cases, minimum, average and maximum (by example, an invoice with only one line, an average size invoice, and a very long invoice). To answer to confidentiality concern by the customer, the best way is to have them black out the name and address of their customer before sending the documents. After all, you are interested in the method, not the names. When the process is done remotely, documents should be scanned and send as PDF or images.
B) The next step is to create a general description of the hardware already in place or necessary for the solution. By example:
1. Each users' group work independently (no information is shared between groups).
2. Each group is made of n users (n typically between 3 and 15) all present in the same office/with some of them using laptops and working part-time on the road/with some of them needing to be able to work independently and synchronize their data later for the following reasons...
If some hardware is already present, you'll need to describe it and to add the enhancements, if any, desired by the client/new application. A common example is to put in place a new software allowing salesmen to take orders while at their customers places of business and to transmit them easily to their central office, the current method being pen/paper and fax. This will mean a change of the hardware in place at the same time than the software development.
If there is no hardware in place, it is very important to give good advise in that phase (even if you are not selling the hardware in question). You will need to ask the customer a precise description of who will do what, when and where to assert the best possible hardware/software solution.
C) You will also need to establish a list of all your main correspondants (name, email, phone, etc) for each module described in A.
You will rarely find a case where one person knows in details ALL the practical aspects of an organization. Several correspondants can of course be listed for each module.
Each person listed will be responsible for the timely transmission of the detailed information send to you for each module. Choosing them correctly is therefore very important.
Of course, once phase 1 has been done by the customer, he shall send the result (shouldn't be more than 2 or 3 pages) to the consultant (me).
D) Specific conditions
A description of some specific conditions can be included in the requirements list or setup in a separate document. I will not go here in to the details of what they can be. As their name implies, they are very often specific to each project. But you will have to think about talking with the customer about them and to write down every one of them
Here are some examples of specific conditions:
- The customer wants to be sure that a license for each of his 40 offices is included in the development price
- The customer wants full propriety of the source
- The customer wants the sources to be safeguarded by a lawyer, in order for them to be available to him in case of a default from the developers company
- The customer wants software maintenance for the first year included in the development price
- The customer wants technical support on the developed software available 24/7
- Development shall be done in a maximum time of...
- A description of setup procedures, employees formation, software update and so on can be included here
- Recuperation of data from other software can be described here...
Very often, the customer will think that because he is giving you information to create the software, he is automatically entitled to some (or all) of the intellectual property rights on it, and that if the software originally written for them is then resold later, they are automatically entitled with a share of the profits. Of course, laws vary from country to country, but most of the time, there is nothing automatic about this, and everything should be clearly detailed in your requirements list.
So when you are writing a requirements list and the corresponding estimate, these points should be reviewed with the customer and the decisions taken written clearly in your contract.
Phase 2: Questions and answers
Based on the phase 1 resulting document, I create a list of questions about the modules described in 1-A, a more technical description about the architecture described in 1-B and possibly a legal and/or technical description of the specific conditions described in 1-D, with of course some alternative solutions proposals, a description of the potential problem of each choice, etc.
I then send the questions/proposals to each concerned correspondant (and a copy to the main correspondant, of course) following list 1-C and I then do a constant follow up of the answers received (or not).
During this process, I maintain a tree of the questions/answers viewable at any time by the main correspondant, and if desired by the per module correspondants. It is done as a web page (not linked to anything else and protected by a password, for evident confidentiality reasons, with also a tree of all the different steps and links toward the corresponding documents.
This page will look like the example below. Each underlined text is a link toward the corresponding document. Dates in red show what answers have not yet been received and allow for a quick and easy way to see what remains to be done.
The allowed duration between the sending the question and receiving the answer is generally one week, in order to let the correspondants process the problem on top of their usual workload without making the realization of the requirement list impossibly long. This duration is generally agreed upon with the customer at the beginning of the process. It can be increased or reduced depending on the circumstances.
1. Customer management module including:
1.1 Customer form (May, 13 2006)
Sent to M.X (May 13, 2006). Answer to be received before May 20, 2006
Sent to M.Y (May 13, 2006). Answer to be received before May 20, 2006
1.2 Invoicing (May 13, 2006)
Sent to M. Z (May 13, 2006).
Answer received on May 18, 2006
Sent to M. Y (May 13, 2006). Answer to be received before May 20, 2006
1.3 Payments reminders management (May 13, 2006)
Sent to M. A (May 13, 2006).
Answer received on May 20, 2006
Secondary questions (delays and reminders texts) sent to M. A (May 22, 2006). Answer to be received before May 29, 2006
Sent to M. Y (May 13, 2006). Answer to be received before May 20, 2006
1.4 Commercial mailing management (May 13, 2006)
Sent to M. B (May 13, 2006). Answer to be received before May 20, 2006
Sent to M. Y (May 13, 2006). Answer to be received before May 20, 2006
2. Appointments management system (May 14, 2006)
Sent to M. C (May 14, 2006). Answer to be received before May 21, 2006
Sent to M. D (May 14, 2006).
Answer received on May 19, 2006
Sent to M. E (May 14, 2006). Answer to be received before May 21, 2006
Sent to M. Y (May 14, 2006). Answer to be received before May 21, 2006
3. Mail management system: scan of received mail and recording of the corresponding actions taken (May 14, 2006)
Sent to M. F (May 14, 2006). Answer to be received before May 21, 2006
Sent to M. Y (May 14, 2006). Answer to be received before May 21, 2006
Each time I receive an answer, I modify this page to show it, put a link in place toward the corresponding document, sometimes send additional questions and of course include the received information into the corresponding chapter in the requirement list.
If an "answer to be received before" date is not respected, I send a reminder to the correspondant who is late and to the main correspondant. This system generally allow to receive answers in a reasonable delay. As long as the answer is not received, reminders are made both by email and phone. It is clearly a balancing act between obtaining answer and alienating your correspondant, who, most of the time, are not answering because of their normal workload, not because they don't want to…
This phase will contain as many cycles as necessary and will produce for each cycle a more complete requirement list.
At this stage, the original list is much more detailed (by example, the payment reminders management includes sub chapters for each of the reminder types, with delay, texts, to dos, etc.) and each line of the list includes/Links to a description text as precise as possible, with mock up screen when necessary).
When the requirement list has become consistent enough (i.e.. when I do not have any more unanswered question), it is recommended to go though a comments phase by the future users of the software:
Phase 3: Comments
This phase is not MANDATORY, but it insures that problems judged unimportant by the decision makers (or unknown from) while blocking users every day have a chance of begin incorporated into the requirement list, and that the experience and know how of the everyday worker in the company may be used in the future tool:
A) The requirement list being organized from the start in modules matching each separate activity listed in 1-A, each part is sent (once again as a PDF) to:
- Either all the future users
- Or a group of users selected as being the most efficient, as volunteering for the task, or any other means decided by the client.
The second method is generally more efficient, especially because the users in question will also be needed during the testing phase.
Each recipient has a specific time to read and comment on the document. If the users do not understand the document or part of it, they are supposed to ask questions about it, and these questions are very often more interesting and revealing than precise comments.
Once again, I'm making a tree visible on the web by the main correspondants with recipient names, answers time, answers received and in case of questions, dialogs started...
Depending on the company culture, it is sometime difficult to involve the final users. To improve the quality of the information gathered, it may become necessary to create an anonymous idea box.
B) Once part A is finished (module by module), I am creating a summation of the comments/questions/answers and I am sending it to each main correspondant, with of course my own reflections/idea on the each point.
Documents sent, answer dates, etc are also made visible on the web tree.
Once answers are received, the desired/necessary modifications are included in the requirement list, then this phase is repeated to verify that the solutions found/chosen do not create other problems at the users' level.
Several cycles at that level are often necessary to obtain a solution which the users will actively support.
Begin able to get this active support means that the users will be impatient to use the new system and that the implementation phase will get way less human resistance.
This aspect of the software creation is largely underestimated by a lot of developers and generally TOTALLY ignored by the client before their first deployment experience (and often even after, considering that it's much easier to blame the development team for the implementation problems than to accept the fact that the company employees are fighting the new system).
Once this phase is done, you will get a requirement list to submit to each correspondant for approval. Once again, a web tree for submission/approval is set up to allows a good follow-up. If there was no big mistake in the previous phases, approval by each correspondant should be a formality.
Please remember that each module may contains several options sometime incompatibles between with each other. Described functions may be optional, wished, but with a realization possible only if budget allows, or maybe in a second development phase.
Phase 4: Estimate
Granted, the estimate is not really part of the requirement list... It is the step following the establishment of the requirement list.
Also, it is clearly possible that once the requirement list has been created, the client will use it to require estimates from other companies and may decide to have the development done by somebody else than you. It is even often the case with big projects.
One other thing to realize is that it's only when the requirement list reaches a deep enough level of details, as described above, that a precise estimate can be made...
However, experience shows that even with all these precautions in place, modifications will be either requested by the customer during the implementation phase, or will be just made necessary by technical problems not foreseen before.
Personally, when I'm giving an estimate to a customer, my billing will exactly conform to it if the development conforms to the requirement list. If modifications are made necessary because of a mistake on my side, I am not billing them. If modifications are requested by the customer, they are estimated precisely and billed accordingly (except if they involve only minor changes, but that is determined by me only, as the apparent simplicity of a change has no bearing on the real complexity of the realization).
These conditions are my normal general conditions. They give each side a high level of security: what will be realized is described precisely in the requirement list.
In the software industry, over budget processes are very frequent. These cases are very often due to very poorly redacted requirements lists sometime entirely internally by the customer and in an alarming number of cases, full of errors, incomplete description, and reference to document or information NOT included in the requirement list or it's annexes.
Clearly, you won't make any friend by sending back such a requirement list to a potential customer with a list of reasons why it is utterly unusable… However, if you don't and accept the job, be fully ready for a very chaotic ride.
I hope that this document will prove useful to some of you, maybe as a guideline for future projects.
Please do no forget that if you want me to, I can do this work for you. I can work directly with your customer to establish the requirement list and then let you do the development phase, or work directly with your company for the requirement list and let you after that choose between any number of estimates based on it
How much will it cost?
Clearly, it depends on the project complexity, number of correspondants to manage, etc.
I propose two different methods:
- Real time invoicing: For each document created, sent, answer read/inclusion in the requirement list, published on the web, etc, the real time is documented and regularly published on a web page accessible by the main correspondant at any time. Each week (by example), an invoice including that documentation is sent and payments are made on reception It is generally the method used for big projects, when it's not possible to evaluate at the beginning the amount of work necessary.
- Estimate: After receiving the initial description, and if the project is not too complex, I will give you an estimate for the creation of your requirement list and establish with you a payment calendar, all that based on my experience in creating these documents.