• INCOSE Requirements Management Tools Survey - This survey, provided in table form, compares over 40 different requirements management systems based on how well they conform to over 75 common requirements. Information ranges from as early as 2004 to the summer of 2008, so you’ll have to bear in mind that some of the information may not be the latest and greatest. The INCOSE survey at least gives you a start and can save you quite a bit of preliminary information gathering work regarding the various tools available in the market, and some initial requirements. If you’re interested, here is a text version of the survey requirements.
  

• Forbes.com also provides a directory of requirements management tools that can be filtered by popular features. I’d refer to the INCOSE survey first, but there is some good information here as well.

• Seilevel’s Requirements Management Tool Selection - I’ve always enjoyed the Seilevel blog and message board as a resource for business analysis insight. In post linked above, Joy shares Seilevel’s process in selecting a requirements management tool to recommend to their clients. She also provides a useful comparison between three “heavy hitters” in the requirements management space - Telelogic (now IBM) Doors, Rational Requisite Pro, and Borland Caliber Analyst. I won’t steal their thunder and share their final recommendation here, but advise you to go have a read.

• Ralph Young has an interesting document on his site that outlines his process and requirements for selecting a requirements management tool. His document compares a few of the leading tools, but the document is from 2002, so it is more useful as a template to use to pattern a selection process than as a resource to decide between the listed products.

• In a separate post from the one mentioned above, Seilevel also shares their requirements for deciding on a 3rd party solution provider and describes how this process is different from the requirements process for home-grown software. My company has been following a very similar process in choosing our management tool.

I will probably have more to share as we continue our selection process, but hopefully these will make a good start. If you know of any additional, useful resources for evaluating requirements management tools, I’ll be grateful if you’d share them in the comments below.

Originally posted on JonathanBabcock.com as:

Requirements Management Tool Resources

Do you like to look at examples of others’ requirement specs and templates to see what you can learn? I do from time to time and thought I’d share a quick, simple tip that I use to find sample documents. Hopefully some of you will find it useful.

There are so many varieties and formats of software specification documents. Looking at samples from other companies and industries gives me an opportunity to compare the way things are done in “my world” to how they’re done across the world.

Once in a while I’ll find something - maybe the document layout, or just a concise turn of phrase - that someone else is doing that I like and will try to incorporate it into my work. Even if not, I find it interesting to observe the varying levels of specificity and requirement format/syntax that others use.

If you think that you, too, may be interested in taking a look at what others in the field are doing, an easy way to find hundreds of examples is to go to Google and type in:

Software Requirements Specification filetype:doc

It will bring up enough samples and templates to keep you busy for a while, and obviously you can tweak the search to bring back slightly different results.

For example, you might try a variations on the search string like “functional requirements” or “use case” or change the filetype to pdf (filetype:pdf) to bring up specs in pdf format.

Anyway, nothing groundbreaking here, but hopefully this will be useful to a few of you.

Originally posted on JonathanBabcock.com as:

Looking for Sample Requirement Specifications and Templates?

[S]omething or someone which exists outside the system under study, and that take part in a sequence of activities in a dialogue with the system, to achieve some goal: they may be end users, other systems, or hardware devices. Each use case is a complete series of events, described from the point of view of the actor.

Ivar Jacobson (1992). Object-Oriented Software Engineering. Addison Wesley Professional. ISBN 0-201-54435.

To further clarify, the OMG in their UML spec describes an actor in the following terms:

Actors may represent roles played by human users, external hardware, or other subjects. Note that an actor does not necessarily represent a specific physical entity but merely a particular facet (i.e., “role”) of some entity that is relevant to the specification of its associated use cases. Thus, a single physical instance may play the role of several different actors and, conversely, a given actor may be played by multiple different instances.

UML Superstructure Specification, ptc/04-10-02, October 8, 2004, p. 661 – emphasis mine.

I’ve found that it’s easy to identify the actors that are users of the system, but sometimes less evident to identify other systems or non-human participants in the use case dialogue. This can be especially true for those that are new to writing use cases.

I’ve always liked quick, little job-aids that help break down and simplify things. To that point, Miles and Hamilton provide a simple diagram for identifying actors in the book Learning UML 2.0 (Learning). I’ve made some minor tweaks to the diagram and included it below in case it might be of use to some of you:

Originally posted on JonathanBabcock.com as:

Quick Tip to Help Identify Use Case Actors

Here are some of my recent findings of interest that I wanted to share in case others of you may be in the same boat.

Martin Fowler specifically addresses the question, “What is the difference between UseCases and XP’s stories?“:

Use cases organize requirements to form a narrative of how users relate to and use a system. Hence they focus on user goals and how interacting with a system satisfies the goals. XP stories… break requirements into chunks for planning purposes. Stories are explicitly broken down until they can be estimated as part of XP’s release planning process. Because these uses of requirements are different, heuristics for good use cases and stories will differ.

Mike Cohn, whom I’ve cited before on the topic of user stories, provides insight on a format for articulating user stories that he has found to work well.

I advocate writing user stories in the form of “As a <type of user>, I want <some goal> so that <some reason>.”

For example, “As a corporate finance user, I want to know yearly how much in taxes are due to the state treasury so that the company can comply with state tax regulations (and avoid penalties for non-compliance).”

I think this format could be just as beneficial in a non-XP environment as a mechanism for requirements elicitation. In fact, I’m going to use the spreadsheet form of which he provides a sample for use in one of my new projects. I plan to ask my stakeholders to put themselves in the place of the user (in at least one case, the stakeholder will actually be one of the users) and let them state, from a first-person perspective, what they need to be able to do, and the value of being able to do it.

Too often as I’ve written traditional SRS documents I’ve either been asked or wondered to myself what was the value of a given requirement or set of requirements. With this format, we’d include a statement of business value with each user requirement. Good stuff.

For your reference, and contrasts them with traditional requirements.

In summary, here is what I’ve gathered so far based from my readings on user stories (much of this is derived from ExtremeProgramming.org’s useful description of user stories) :

1. User stories are primarily used to estimate development time, as opposed to use cases which focus on how users (actors) interact with a system.
2. User stories focus on user needs and are technology/implementation detail agnostic.
3. User stories become acceptance test scenarios.
4. User stories are typically written on cards and not diagrammed using the UML as are use cases.
5. User stories are an alternative to the traditional SRS document full of “shalls”. When it comes to detailed functional, system and quality requirements, those are worked out between developers and the customer.
6. User stories are most often identified with the XP (extreme programming) approach to release planning and development, which is a form of agile development.

I am a student as much as a practitioner of requirements analysis, and am always open to new information in tips. If you have any additional information or personal feedback on user stories or extreme programming or other agile methods, then please share. I’m always interested in learning more.

Originally posted on JonathanBabcock.com as:

More on User Stories

This modularity can be undermined, though, if we allow our use cases to get too far into specifics and implementation detail.

The book Use Cases: Requirements in Context (2nd Edition), by Kulak and Guiney, provides us with a couple simple ways to self-check our use cases to ensure that they include the appropriate level of detail, but aren’t reaching too far into design.

Use Case Naming

According to Kulak and Guiney, there are guidelines to naming use case that can help keep them at the appropriate level of detail. Use case names:

• Should conform to verb-noun construction: mail checks, determine eligibility, trace shipment, print letter
• Can contain adjectives or adverbs
• Should not contain any situation-specific data
• Should not be tied to an organization structure, paper forms, computer implementation, or manual process: enter form 104-B, complete approval window, get approval from immediate supervisor in Accounting DepartmentShould not use “weak verbs” … that do not describe the action: process, complete, do, track

One of my stumbling points when I first began authoring use cases was that I was prone to getting into the “who, what, when, where and how” in my use case names. Doing so isn’t necessarily wrong from a correctness standpoint, but it certainly undermines what is, as I mentioned above, one of the best things about use cases: their modularity. A name that is that two lines long is probably indicative to deep a level of detail in the use case. What I prefer to do now, and what I think it pretty standard, is to use the use case goal as the name.

So, the use case name should be brief, concise, and indicative of what the use case is accomplishing. Obviously, you can give a use case a short name and still include too much fluff, and this tip is offered more as a “helpful hint” type of tool than a fix-all. Here’s another way to check your use cases for appropriate detail:

Is “the system” stealing the show?

Does the use case take a user’s (actor’s) perspective, or does it appear that the user is just along for the ride while the system steals the show? Kulak & Guiney’s tip here is this:

When design creeps into a use case, it becomes quite obvious. When the system is performing several steps before responding to a user, it sounds an alarm that perhaps internal system design is being created and exposed.

Do you sometimes look back at your use cases and have to admit that they are difficult to distinguish from fully detailed test scripts, replete with steps including buttons to click, screens to access, where the system is going to grab a certain piece of data, etc.?

We get off the use case “straight-and-narrow” when we begin including detail in the steps of the use case that may need to change based on how the use case is implemented. Whether we use buttons or text links; 1 screen or 5 screens; or jsp’s, asp’s, or php’s, the user goal is the same. We want the steps of our use cases to include what a user or system must do to accomplish the goal, not on all the dirty details of how, and all the intricate functions the system may have to perform to support the user goal. That’s not to say that some of that detail doesn’t have it’s place in the use case. By all means, include business rules with use cases - but in a business rules section, or in a separate business rule repository and not as steps in the use case.

Anyway, I am finding the book to be an easy read and a nice resource of practical information on how to effectively express requirements through use cases. I’d encourage you to grab a copy of the book if you want to learn more about use cases, but have a hard time staying with Cockburn’s books, which are great resources, but have never been mistaken for light reading.

Do you have any little tips or tricks for keeping your use cases at the appropriate level of detail? Any preferred books or resources on use case basics? If so, please feel free to share. I always appreciate your comments!

Originally posted on JonathanBabcock.com as:

A Couple Tips on Keeping Use Cases Simple

To me, it boils down to a few main points.

• Uniformity of requirement structure
• Clearly defined requirement syntax and project vocabulary
• Attention to grammar and word usage
• Repeat, Repeat, Repeat

In this post, I’ll cover the first bullet - requirement structure, and touch on the last.

Uniformity of requirement structure

I’ve always thought it logical to apply a consistent structure to each requirement in a specification, but it was in a recent training session that I was shown a simple technique for ensuring consistency. It isn’t a major process breakthrough, or a cutting-edge meeting management technique. As I said, it is actually a very, very simple. And the simplicity is, in fact, the benefit. Here’s how my requirements will be structured:

Subject + Capability + Constraint*

There it is. That’s my formula. I’ll explain.

• Subject: Every requirement will begin with the subject, or entity performing the action. This will typically be the user of the system or the system itself. In times past, I’d be inclined to start out with a condition, like, “If the user is logged in, the system shall….”, or, “When the order is in open status, a user shall be able to….” Always leading with the subject helps me to avoid writing in passive voice, which might be great for prose, but is less than ideal for requirements.

• Capability: This is what the subject “shall be able” to do. There will be one and only one capability in each of my requirements.

• Constraint: The reason for the asterisk next to “Constraint” is that not all of my requirements will necessarily include a constraint. Most probably will, though. The constraint will be a condition or that will be applied to the Capability.

So, as a sample requirement I’d write:

“A user shall be able to print his/her statement from the account summary page.”

In this case, “user” is my subject, the ability to print the statement is the capability, and the fact that it will be printed from the account summary page is the constraint.

Note that the subject, capability and constraint are also included in the requirement in that order. The reason for this is that uniformity makes the requirements easier to understand.

With “S+C+C”, I’ve found that by using the same formula for EVERY requirement (repeat, repeat, repeat), consumers of my documents became accustomed to the structure and the flow. For a system requirements spec (SRS), many of the document’s consumers are designers or developers who are versed in the language of software development. Logic expressed in software code is very uniform and consistent. Using the same structure for all requirements is - albeit only slightly - more like “speaking in their language.”

Now before I finish, I want to make it clear that there is nothing wrong or inaccurate about stating requirements that lead with a condition, or that vary from my adopted format. My point is that it’s important to pick a way that works for you and your document’s consumers and to not deviate from it. Ever.

I’ll write more on my other main points listed above in the coming days. In the meantime, I’ll be interested in hearing any other ideas you may have on what works and what doesn’t regarding requirement structure.

Originally posted on JonathanBabcock.com as:

Precision Tools: Requirement Structure

Allow me to reflect and maybe even toot my own horn here for just a second. Since I’ve been a business analyst, I think it’s fair to say that I’ve written accurate requirements. By this I mean that they have accurately represented what a user needed to be able to do, and what the system needed to be able to do to meet the business requirements. Despite my presumed accuracy, I’ve faced projects where there has seemed to be an inordinate amount of churn around the wording and language used in expressing requirements - sometimes to seemingly annoyingly inane levels (”Hmmm… That all depends on what the meaning of ‘is’ is….”). Especially as a younger BA, I couldn’t understand why the designers and testers couldn’t understand plain English and just do what the requirements said.

Well, years and experience have tempered me somewhat, and although I still have room for improvement in a lot of areas, one concept has helped me improve a great deal as a business analyst. It has also helped me to understand the angst of the QA analyst and design architect. Today, I’d like to pass it on to those who may benefit from the same lesson. That is:

It’s not enough for requirements to be accurate, they must also be precise.

What is the difference, you ask? Have a look at the image below.

Image above originally sourced from Alcontrol.co.uk.

Accuracy, as you can see on the examples on the right side of the image above, is hitting close to the target. Precision, as evidenced in the top left and lower right examples, is consistently hitting close to the same spot. Obviously, both are important, and the good BA must strive for requirements that are accurate and precise.

So, while I was writing accurate requirements, I was only meeting half of my obligation to downstream delivery teams. To be a good business analyst, I need to communicate in terms that are not only accurate but clear and consistent.

Natural language is inherently ambiguous

The odds are stacked against the BA when it comes to writing requirements that are both accurate and precise, as natural language is inherently ambiguous. The same phrase, punctuated or intoned differently can take on a variety of meanings. For example,

“I, John Doe, am glad to see you here!”

Am I John Doe, and telling someone ( or maybe even a group of people) that I am happy to see him (/her/them) here, or am I addressing myself to John Doe and telling him I am glad to see him here? The statement is accurate, and both are are valid interpretations of the sentence, but only one is the correct result. This is an example of the difficulty I was experiencing with my “accurate requirements”. Different people can understand the same phrase differently depending on the individual and the context. So, how does a BA cope with this?

Some shops adopt different, more precise ways of expressing requirements such as UML, pseudo code, and formal specification language. Here are a few examples of alternatives and how they compare to natural language requirements:

• Natural Language which includes your typical “user shall” or “system shall” requirements. These are considered the most “understandable” because natural language is the language in which we speak and write. In theory, anyone who can read the language should be able to understand what the requirements are saying. For example, a business stakeholder who has no technology experience, and doesn’t care to bother learning UML or more precise forms of specification will prefer natural language requirements. In my experience, we pretty much always write up our business requirements in this way - be it just a list including vision and objectives, a few user stories, or whatever the case may be. As we mentioned before, natural language is the most open to multiple interpretations and hence the least precise method.

• Structured Languages like UML that represent natural language through the use of graphics and rules within a structure where each element has a distinct meaning. The symbols and notation rules in UML allow for it to be a more precise means of expressing requirements. UML is still relatively easy to understand, but not as easy as natural language as it does require a little bit of study or training to understand the ins-and-outs. UML diagrams - especially activity diagrams and use case diagrams - are a great alternative to natural language as a way of expressing user and functional requirements.

• Pseudo Code, or more descriptive languages include if/then/else and other logical statements that read as much like code as they do natural language. It doesn’t necessarily resemble any one particular programming language, but uses common syntax and attributes that allow it to be flexible across technologies. Again, the rules, conventions, and structure of this type of method makes it very precise, although very difficult to read for those that aren’t familiar with the language and logic of software development. Detailed system and design specs are most likely to include this type of language.

• Formal specification language goes a step beyond pseudo code to include mathematical logic and a code-like format. I’ve never been in an environment that uses this type of specification, but I’ve been told that it is common in aerospace and weapons technology - where lives are at stake, and precision is of the utmost importance - and the user group is familiar with the technical terminology. If you’re curious, here is a link to a page that describes some of the syntax of formal specification language below. Wikipedia also has a worthwhile entry. This link describes the different types of formal specification languages. I’ll also give an example just to emphasize the low-understandability aspect.

Delete(Insert(s, e), e’) ==
if e=e’
then Delete(s, e’)
else Insert(Delete(s, e’), e);

How do I write accurate and precise requirements?

This post is addressed chiefly to the good, old natural language requirement writer, though. Given that natural language is the least precise method of expressing requirements, and given that we need to increase the precision of our requirements for them to be of good quality and use to their consumers, what do we do?

We make our requirements reliable. We make them consistent in form and structure. We adopt a limited, well-understood vocabulary and stick to it. We make our requirements “boring”. This allows us to ensure that each arrow (requirement) is hitting very close to the last. It gives us precision in addition to our accuracy. I have some ideas on how to standardize requirements and make them more consistent and precise, but I’m getting a little long-winded here, so I think I’ll share those in a different entry.

My main point here, and I hope I’ve been able express it adequately, is that the business analyst’s job is not complete if the requirements are written and accurate but not precise. The key is to find a way of articulating requirements that is as precise and as easy to read by the target audience as possible. I’ve found that as my requirements become more precise, the churn around language and semantics decreases significantly. I suspect that many BA’s may find the same to be true.

Anyway, look for follow-on posts in the coming days that will address requirement structure, requirement vocabulary, and any other tricks of the trade I’ve picked up that I think worthwhile to pass along.

In the meantime, take a quick look back at the image detailing accuracy vs. precision. I found it interesting to briefly contemplate the ways that writing precise but not accurate, or accurate but not precise requirements could impact a project.

As always, I’ll be glad for any comments or experiences that you may have had in dealing with issues of accuracy and/or precision in your requirements.

Originally posted on JonathanBabcock.com as:

Good Requirements Are More Than Just Accurate

I found a great deal of help in Mike Cohn’s article, Advantages of User Stories for Requirements. In this article, Cohn explains user stories and the advantages of using them over traditional, natural language requirements and use cases.

Below is a brief synopsis, but you’ll really want to read the full article. Mike has gone to a fair amount of detail providing useful, practical examples for comparitive purposes.

On the composition of user stories:

Each user story is composed of three aspects:

1. Written description of the story, used for planning and as a reminder
2. Conversations about the story that serve to flesh out the details of the story
3. Tests that convey and document details that can be used to determine when a story is complete

On the weaknesses of natural-language requirements specifications:

• IEEE 830-style requirements (”The system shall…”) are “tedious, error-prone, and very time-consuming.”
• Traditional requirements are boring to read, which means that for longer documents, readers are inclined to skim through the document and skip sections.
• Traditional requirements focus on a “checklist of requirements rather than the user’s goals.”
• It is difficult to prioritize individual requirements listed in a specification of hundreds of requirements.
• It isn’t practical to provide budget and time estimates for individual requirements, but it is for user stories.
• User stories are more reader-friendly and easier to prioritize.

Comparing user stories to use cases:

• Use cases typically convey larger scope than user stories. User stories are purposely capped to fit within a targeted delivery time frame.
• A user story basically corresponds to the main success scenario of the use case.
• Use cases often become permanent system documents; user stories “are not intended to outlive the iteration in which they’re added to the software.”
• Use cases often include interface and implementation detail. User stories do not.

Cohn is pretty convincing, and, having read his article I definitely understand some of the merits of user stories. However, I am left with a few questions to research. For example, I understand that user stories are not intended to serve as system documentation. Often they’re torn up and tossed after the iteration in which they’re implemented.

I think there is great value in having a documented repository of system requirements or use cases, though - basically a snapshot of what our system does today. I wonder how that is addressed in an environment that uses user stories for requirements?

In any case, Cohn provides a great starting point for understanding user stories, and I’m certainly interested in learning more.

Have any comments or successes to share on user stories? I’ll be interested to hear them.

Originally posted on JonathanBabcock.com as:

What are user stories, and why should I use them?

Now that I’ve sat through some of the training, and gotten a quick peek at some of the tools available, I wanted to appeal to my audience here for some guidance regarding modeling tools.

I’ve dabbled a bit with Enterprise Architect (I’ve downloaded the trial). It seems pretty complete and it very reasonably priced. I downloaded StarUML a couple days back and began playing with it a bit. The best thing about StarUML is that it is open source (free!). It doesn’t seem quite as user-friendly as EA, but you can’t argue with the price. There also seem to be some add-on features for it that might make it more appealing. I’ve also looked at ArgoUML in the past, and it is ok. It doesn’t appear to be up to UML 2 standards yet, though.

Other than that, there are, of course, the Rational and Borland tools which are great, but are probably overkill - especially in terms of price - for what we’re doing.

Honestly, I’d be fine with what MS Visio offers if I could just figure out a way to print use case diagrams with the accompanying text attributes. I haven’t been able to figure out for the life of me how to get that to work, though.

I’m not asking for much, either. Basically, all I need is a tool that allows you to:

• Output to Word or PDF
• Output the diagrams AND accompanying text (i.e., main success path, preconditions, postconditions, goal, etc.) in a usable/readable form.
• Create links and relationships between use cases across an entire system.
• Cost efficient - we’re not hardcore. We just want something that meets the basic requirements above.
• This is gravy, but it would be great if version control were built into the tool.

So, can you help a fella out? What UML modeling tool(s) do you prefer? I’ll be glad to hear your comments and words of experience/advice.

Originally posted on JonathanBabcock.com as:

UML Use Case Modeling - A Little Help?

Basically, the article consists of a list of common requirement quality attributes (you know.. complete, correct, unambiguous, etc.) accompanied by questions that can be used as a checklist to ensure that your requirements meet the criteria of each attribute.

Firestone points out,

[J]ust as we all had to learn the rules for writing grammatically correct English, we also have to learn the rules for writing high-quality requirements. And just as not everyone who can read and write can also author a publishable book, not everyone who can write individual requirements can organize them into a high quality requirements specification. Whereas the rules for properly specifying individual requirements are relatively easy to use once you learn them, experience shows that they are also not obvious to most people who actually specify real requirements on real projects.

Considering that these rules may not be obvious to most, I thought I’d do my part and share the “good word”.

Firestone admits that the information he provides is really a summary of information that is readily available from many other texts and training. There is nothing new or groundbreaking here, but a quick scan of the article may provide some insight on things that you could be doing a little better.

Reference:

Donald Firesmith: “Specifying Good Requirements”, in Journal of Object Technology, vol. 2, no. 4, July-August 2003, pp. 77-87. http://www.jot.fm/issues/issue_2003_07/column7

Originally posted on JonathanBabcock.com as:

Handy Requirements Quality Digest/Checklist