Clinexus - Your Access to Growth

Video 23 - The Software Requirements Specification [Video Transcript]

1. Introduction

Now, everyone and their dog has a software requirement specification template. Here's the one my dog came up with. Actually, I don't have a dog. I used to have a very smart cat, and she helped me with this. This is a fairly robust template that I suggest using for your SRS. You can access a Microsoft Word version of this template from the goodies page at ProcessImpact.com. That template contains a description of what should go into each section, not just the skeleton shown here. You can also access a sample SRS written according to this template from the goodies page at ProcessImpact.com.

This template is adapted from the one shown in I triple E standard 830. You might recall from module one that the I triple E is the Institute of Electrical and Electronics Engineers. I strongly encourage your organization to obtain a copy of the I Triple E software engineering standards collection. On the internet go to URL Standards.ieee.Org/Software for purchasing information. Unfortunately the standards are not public domain, so you do have to buy them. They're well worth the money.

One of the standards, standard 830, is called the, "Recommend practice for software requirement specification," last updated in 1998. Like many of the I triple E standards, it not only gives us some guidance about how to perform those important activities, but it also suggests a structure for a document that we can use to store the important information associated with requirement specification. I've used the I triple E standard quite a few times, and it's generally pretty sensible. It has a little bit of weirdness in it, so what I've done here is to try to modify the standard template to try to correct some of the weirdness, and to make it a bit more straight forward. I highly recommend that you become familiar with the standard 830 if you're going to be writing requirements, because it provides a lot of useful guidance.

I like document templates for a couple of reasons. First, they give me a consistent way to organize information from project to project. They also remind me to ask questions. Maybe we've been filling this template out as we've been exploring requirements. Then we notice that we don't have anything in section 2.5 for design and implementation constraints. What does that mean? Have we not discussed constraints yet, or have we not organized the information properly so something that really is a constraint is stored someplace else? Maybe we need to have a conversation about constraints with our customer representatives and see if we've missed anything.

If you really don't have any constraints, just say so in this section. I prefer to do this than to remove a section that you don't have anything to say from the document. If you remove that section, the reader doesn't know what that means. Hey wait, aren't there any constraints? By leaving in the section title and just stating that no design or implementation constraints have been identified, the reader knows that you thought about it and came to that conclusion.

2. Overall Description

Chapter 10 of the software requirement second edition book describes this template in some detail. I'm not going to go through the entire template right here, but I'll hit some highlights. Section one contains some header information. There's a section for project scope. Now, if you have the scope defined somewhere else, perhaps in a vision and scope document, don't duplicate that here. You can include materials simply by pointing to the other source, thereby including it by reference. That's fine. Product perspective in section 2.1 says something about where this system that you're specifying fits into the universe. Is it the next member of a growing product family, or is it version N plus 1 of a mature product, or is it something brand new the world's never seen before? Are we replacing a legacy system or two?

We might have a list of major product features. Again, we had a place to list features in the vision and scope document. If you decide to use both of those documents for your project, you'll need to do a little bit of adjustment to remove some of the duplication. We don't want to duplicate information across these documents. I present the templates even with a bit of duplication because some people will use one, some people will use another, and some people will use both and have to do a little adjusting. We can describe our user classes and their characteristics in section 2.3. design and implementation constraints go into section 2.5. in 2.6 you can describe whether you've planned to create any user documentation, such as help screens, or tutorials, or reference manuals.

It's a good idea to make a note of any assumptions and dependencies you're aware of in section 2.7. an assumption is a statement that we treat as being true in the absence of definitive knowledge that it is true. Stakeholders often hold different assumptions, and if we don't get those out on the table people can work across purposes. For example, one person might assume that a certain set of functions will be custom written for this application, while someone else assumes that they'll be reused from a previous application, and a third person assumes we'll be integrating those functions from a commercial third part library. We need to straighten those sorts of things out.

3. System Features

Where is the beef? Well, in this template the beef is mainly in section three. That's where we're going to detail our functional requirements. There are many ways you can choose to organize that section. My triple E standard 830 suggests several different organizational schemes, and you can use combinations of those as well. Just for the sake of illustration here I've chosen to organize this template by system feature, but you might also organize it by use case, that's fine. You might organize it by functional areas such as printing functions, security functions, things like that. Alternatively, you could choose to organize it by mode of operation, user class, or object class. Again, I suggest you become familiar with the I triple E standard, because it helps you think about some of the various organizational options. There's no right way to organize requirements, use whatever approach makes the most sense for your project and situation.

Maybe we've got system feature number one. We list it's name's, such as spellcheck. We describe the feature and state it's relative priority to the other features in the SRS. We list the major stimulus response sequences, the events that take place in what the system does in response to each one. These stimulus response pairs are like the very top level description of the use case, the dialog between a user and a system at the highest level. Then we itemize the individual functional requirements for each feature. Remember, you don't implement a feature. You implement a set of functional requirements that, in the aggregate, constitute the feature. Now you repeat this block of information for however many things you have that you chose to call, "Features."

4. External Interface Requirements

Section four provides a place to document external interface requirements. I don't normally recommend putting the detailed user interface designs in the specification here for several reasons. First of all, it's called, "Design," so perhaps it doesn't belong in a requirement spec. People already get frustrated by how long it takes to develop and agree upon the requirements, and if we include doing all the user interface detailed design as part of that process, people are going to get even more frustrated. Also, the person who's doing the user interface design, such as a usability engineer, might not be the same person who's writing the requirement specifications, the analyst. They could be the same person, but they might not be.

Now I'm a lot more comfortable putting user interface details into an SRS if we're making a chance in an existing system. It makes more sense because we've got a current reality, and a lot of existing constraints to work within. Sometimes they're just modifying some fields on a screen or something, then I have no problem with including the screens in the spec, because it helps with the communication. I also have no problem with including what I call, "Sketches," here. They might even be actual screenshots, but conceptually they're sketches that say, "Here's another way to represent the information about these requirements." You're not committed to building it in exactly that form, but the screens provide a tool to help communicate what we're thinking about.

You want to be very careful to avoid relying on simple screen designs, or prototypes as a substitute for the detailed functional requirements. Screen design shows you one aspect of the requirements, but it doesn't show you things like all the possible values for a certain field, it doesn't show you the logical relationships between fields. Screen designs just show a superficial view of the requirements. There's a lot going on behind the scenes that we need to describe more fully in the form of functional requirements.

Some other information you might put in the section on use interfaces would be any standards you're going to be following. Is the F1 key always going to bring up some contact sensitive help display? Will you have standard navigation bars at the top and bottom of every webpage? Do you have color and style standards? That sort of thing.

In the section on interfaces to external pieces of hardware, I wouldn't include routine items like printers and storage devices that your computer's talking to. We're talking about components that are application related, such as a bar code reader, a sensor, or a machine your software's controlling. The rest of section four describes interfaces between your system and other software components, and any communications protocols or requirements between the system and the rest of the world.

5. Other Nonfuctional Requirements

Section five is a place to describe other non functional requirements, external interfaces being one kind of non functional requirement. Performance requirements are also a type of non functional requirements. There's this whole universe of software quality attributes. I've called out two of those, safety and security, into their own sections. The reason I did that is because on most systems safety and security are either extremely important, or not important at all. If you're developing an ordinary information system, there probably aren't any safety requirements because people are rarely injured by a defect in Tesco software, but security of the data might be essential.

However, if you're building a piece of electrical equipment you have a number of absolutely vital safety requirements. Any other quality requirements can go into section 5.4. You could slice and dice these sections differently from how they're shown here. You might repeat a block of non functional requirements in each feature description in section three. Let's say for example that your next application included two features, spellcheck and real time missile tracking. I don't know if you build systems like that. My guess is that the performance requirements are a little bit different for spellcheck and for real time missile tracking, so it doesn't make sense to have just global quality attribute and performance requirements for very different features.

Of course you may add as many other sections as you need to this template. We used a template very much like this when I worked in the web development group at Kodak. We added a section for internationalization requirements, because that was extremely important for our corporate website. You can attach some appendices with either a logical or a physical staple, a glossary of important terms is an excellent idea. You might have drawn some analysis models, which I'll describe in module eleven. You might also have an issues list that contains any TBD's, things you're waiting to be resolved, or other open issues and questions that could gradually go away. Sometimes I attach the data dictionary as an appendix to the SRS.

This template provides a suggestion for how to organize the variety of detailed software requirements information. If you do a web search you can find many, many other requirements templates available, but this is as good as anything and it's worked well for me in a variety of projects.


Now, on a very large project you'll have multiple levels of requirements. I worked with one company that was building a very complex process control application with more than 100 people working for multiple years. This project had about 800 high level system requirements. The project was divided into 20 sub projects, each of which had it's own SRS, which was typically 800 or 900 requirements derived from the overall system requirements. A large project becomes unmanageable if you don't take a divide and conquer approach.


Return
Jan 29, 2017 Category: Articles Posted by: admin

Focused on You

If you...

  • are a small or medium-sized business
  • have a health technology application
  • are ready for growth

Contact us today.

 

Prosthodontic Associates