Writing Software Requirements for Developers

by Krishna on September 26, 2007

Writing requirements is difficult. Most, if not all, requirements documents are generally incomplete to varying degrees. When developers start coding, they realize that certain conditions are not addressed and get stuck. At this point, someone has to step in and fill the gaps.

Achieving 100% complete requirements is an impossible and highly expensive goal, not least because business needs keep changing. However, there is such a thing as inadequate requirements. When requirements are not enough, developers have to spend time to find the missing pieces. And if they resort to assumptions, the result is costly re-work.

One way for an analyst to create better quality requirements is to continuously think of what the developer would want to know. Requirements document what the customer wants to build. But unless the analyst anticipates questions that will arise during development and gets them answered, then such documents will keep developers on edge.

Let me elaborate upon this. Let us take any business entity in the application such as an employee or department record. Here are some of the questions that would need to be answered:

  1. Operations: What can users do with this record — Add, View, Edit, Update & Delete? What are the restrictions on such operations? For example, the customer may not want users to delete employee records at all. A clerk cannot edit the Point-of-Sale information, but can only add a correction. A mechanic may want to do a “search” for an inventory part, but probably just see a list of car models.
  2. Security: Who can perform each operation? For example, data entry operators can only do certain operations. Only certain managers can see aggregate reports. No one in the Chicago branch should be able to see the financial reports of the Houston branch and vice versa. A student could only see the names of other students in their class, but the school administrator can also see their Social Security Numbers.
  3. Logging and Audit: Should the application track and record various operations with each record and the user who did the operation? Does the application need to maintain and compare different versions of the record? Should the application have the capability to turn off this audit capability when required? Should there be diagnostic capability to understand the health of the application with respect to data integrity and performance?
  4. Dependencies: How does an operation on one entity affect the remainder of the application? For example, when a sale is made to a new customer, what other operations (such as future marketing) should be activated? Am I prevented from deleting an employee record if I have written some notes on that employee? Or should the notes be deleted automatically?
  5. Locking and Concurrency:  Do multiple users need access to the same record at the same time? What kind of operations can they perform simultaneously? Do we need to prevent access in any way? Will that create any deadlocks? Will users lose data in this process? Thinking about such considerations is very important in applications having shared data.
  6. Ownership and Sharing: Does each record belong to a particular user? Can that user share that information with other users? Can the other users edit that information? Can they share that information further with yet other people? Can a user prevent others from spamming him/her by sharing unnecessary information?
  7. Workflow: What is the lifecycle of each record? For example, a document record may move from one user to another seeking approval. A bug may move from a tester to a developer asking for action and return back to the tester requesting closure. Who can act upon that record at each stage in its lifecycle? What are the possible next stages from each stage?
  8. Data Formats: Can the user export the data to Excel, Word, CSV or some other format? Can they import it back from those formats? Does the application need to provide access to the data through API’s or web services? Can power users directly interact with the data using reporting tools, bypassing the application and its controls?
  9. Visual Formats: Do end users like a form style of data input or do they like a grid? What sort of colors and icons do they prefer? Do they like jam-packed, complex, powerful screens or they prefer simple layouts with large text and buttons? Are they keyboard-people or mouse-clickers? What usability, social and cultural issues do we need to consider?

You don’t need to have all this information. It is likely that your application is much simpler and can eliminate many of these requirements. However, even the fact of stating that something is not a requirement makes it so much easier for developers.

Another reason I put up this long list is that many non-technical customers expect many of these features by default. They don’t have the technical background to convey this information to you effectively. They may even miss telling you important security and workflow information, but expect you to know about it and ask them for it. After all, you are supposed to be the expert.

And if there is no single customer like when you are building products, you have to rely on market research, design standards and innovation to provide you information about these features.

{ 1 comment }

Christian Aimee March 21, 2011 at 9:00 pm

Thanks for the informative post - this was really helpful for me. As an FYI this was the #1 SEO link for the google search term "requirements for developers"; which is how I came to this site. Well done!

Comments on this entry are closed.

Previous post:

Next post: