Information – Kind of vs Form of

Author: Geri Schneider Winters

When working on a project, you want to consider what kind of information you have, and what form is the best for documenting that information. These are two different things. A use case is a form of documentation that can be used for a variety of purposes. Sometimes a use case represents requirements, and sometimes it does not. So do not confuse the kind of information with the structure or form of the information.

Sometimes the easiest thing to do at first is to think of everything as information. As you collect and categorize information, you can decide which things represent requirements of the solution, and which things are other kinds of information. Often when I start a project, I am not sure what I have at first. I’ll collect a lot of information, then I will start to see patterns and categories to that information. As I structure the information into these patterns and categories, the process helps me to determine which things are requirements and which are other kinds of information. After that, I decide what form of documentation to use to communicate that information. I start with the information first, then I decide how to structure that information, what forms to put it in.

A number of companies I have worked for were very focused on use cases. Everything was a use case, the only requirements they had were use cases. But this was causing problems, because all the requirements were not use cases, and they were using use cases for purposes other than requirements. Needless to say, people at these companies were very confused. So instead of focusing on how the requirements were structured (use cases), I focused everyone on the kind of information they were collecting. This information represents context or scope, but that information looks like future state. Once I had determined what kind of information they had, then I guided them to appropriate forms of documentation. I did have use cases for both context and requirements, and I had other kinds of requirements documents as well. This approach cleared up a lot of confusion at those companies.

I have used state machines for analysis and for detailed design. I have used use cases and activity diagrams for context as well as for requirements. A component diagram can represent a logical or a physical model. If you know what kind of information you have, you can make a separate decision about the form you use to communicate that information. Typically the form you use will depend on the audience (or consumers) of the information.

Here are some ideas of what I think of as kinds of information vs forms of information. You may not completely agree with the two lists, but I hope they lead you to thinking about the kinds of information as being separate from the forms of information.

Kinds of information

  • Context
  • Scope
  • Problems
  • Solutions
  • Requirements
  • Future State
  • Needs
  • Wants
  • Dreams
  • Wishes
  • Constraints
  • Limitations
  • Risks
  • Technology
  • Bug Reports
  • Feature Requests

Forms of information

  • Use Cases
  • Shall Statements
  • Test Cases
  • User Stories
  • Scenarios
  • User Interface Designs
  • Wireframes
  • FURPS
  • Prototypes
  • Flow charts
  • Activity diagrams
  • State machines
  • Truth tables
  • Report Specifications
  • Data Dictionaries
  • Data Models
  • Domain Models
  • Object Models
  • Business Requirements
  • Business Rules

 

Do you see that kind of information and form you put it in are two different things? What kinds of information do you work with? What forms of information do you work with?

 

Use Cases Are Not the Only Requirements

Author: Geri Schneider Winters

With all the focus on Use Cases, it can be easy to forget that they are not the only kind of requirements. Use Cases are very good for some kinds of requirements, but really bad for other kinds of requirements. One of our challenges as Business Analysts is to determine the right way to document the requirements for a particular project.

When starting on a new project, one of the first things I want to find out is “Who or what is driving the requirements for this project?”. I was really reminded of this when I read Richard Denney’s book “Succeeding With Use Cases: Working Smart to Deliver Quality”, a book I highly recommend.

If the project is being driven by changes in processes, then Use Cases probably make a lot of sense, since they are good at describing processes. But you could also use User Stories, Scenarios, Flow Charts, or Test Cases to describe processes. Which you choose will depend on corporate culture and the software development process that is used on your project.

In this case, find out what is driving the process change. If the process change is coming from the way that people work, then you can find requirements by talking to the people or watching them work. If the process change is coming from a technology change, then you may need to start working on the requirements by learning about the new technology. I worked on one project which was to design software to run on hardware that tested IC chips. The source of my requirements was the tests that had to be run on the IC chips. I documented those tests as Use Cases because that is what the customer wanted me to use for requirements.

If the project is purely a change in underlying technology, then a lot of your requirements will be the non-functional requirements (often called FURPS). You might have to write these requirements as formal “Shall” statements. Look over a template for a Supplementary Specification for ideas of the kinds of requirements you might need.

For example, if I am installing COTS (commercial off-the-shelf) software, then I do not need Use Cases for how the software works. I might need Use Cases for how we will use the software in our company, if that information is not obvious. But I really need to know other kinds of information, such as how many users will use it at a time, what response is required, how many transactions per second it will have to handle, how many records will it have to store and process, and what kind of security is required to use it. I will have to talk with the folks in Enterprise Architecture to find any restrictions on where or how it can be installed. There may be a need for a new server, so I have to find out the contraints such as what platforms are allowed, or how much money we can spend on it.

In embedded systems, you may find that truth tables or state machines do the best job of describing the requirements. In this case, there is probably no human interaction, and the processes are all closely related to the hardware and how it works. A truth table or state machine is a good way to describe the different states of the system and how it is allowed to change.

Here are some ideas for kinds of things I have seen used (successfully) as requirements for different kinds of projects. Consider these to see if they are appropriate for your projects:

  • Use Cases
  • Shall requirements
  • Test Cases
  • User Stories
  • Scenarios
  • User interface designs
  • FURPS requirements
  • Prototypes
  • Flow charts
  • Activity Diagrams
  • State Machines
  • Truth Tables

 

How do you decide what kinds of things to use for requirements on your projects?

What other kinds of things have you used for requirements for your projects?

 

Alternatives of Alternatives

Author: Geri Schneider Winters

Another great question came from Adesh Sharma about whether or not he could write alternatives to alternatives in use cases.

There is no actual standard for the formatting of a use case, just guidelines and best practices. Your primary goal in writing use cases is communication. No matter how you structure a use case, if the readers do not understand it, then you need to change the use case.

In some cases, you will find that describing an alternative of an alternative makes a lot of sense, and actually improves the readability of the use case. In other cases, the use case will be more confusing.

Here is an example I created specifically to show the use of an alternative to an alternative. I think in this case it reads OK, and may be a reasonable way to document this use case.

Place Order Use Case
Basic Flow of Events
=====================

1. The use case begins when the customer selects Place Order in the order processing software.

2. The order processing software displays an order form to the customer.

3. The customer enters his or her customer id into the order form. If the customer does not have a customer id, go to the alternative “The Customer does not have a customer id”, which is shown below.

4. The system uses the customer id to get the customer’s account information from the customer database.

5. The system displays the customer’s name and shipping address on the order form.

6. The customer enters a product code into the order form.

7. The system uses the product code to get the product description and price from the product database.

8. The system displays a description and price for the product on the order form.

9. The order form adds the price to the order total.

10. The customer enters credit card payment information into the order form.

11. The customer selects the Submit button on the order form.

12. The order form sends the information entered by the customer to the order processing software.

13. The order processing software verifies the information from the order form.

14. The order processing software saves the order as pending in the database.

15. The order processing software forwards credit card payment information to the accounting system.

16. The accounting system sends a confirmation to the order processing software.

17. The order processing software marks the order confirmed in the database.

18. The order processing software displays an order ID to the customer, and the use case ends.

Alternative: The Customer does not have a customer id
======================================================

1. The customer selects create account.

2. The system displays an account creation form.

3. The customer completes the name and shipping address fields.

4. If the customer is a corporate customer, include the alternative “Add Corporate Payment Information”, which is shown below.

5. Otherwise, the customer enters his or her credit card information into the payment fields, and a billing address (if different from the shipping address), into the billing address field.

6. The alternative ends.

Alternative: Add Corporate Payment Information
===============================================

1. The customer selects enter corporate payment information.

2. The system displays a corporate payment information form.

3. The customer selects the pay period, one of Net in 15 days, Net in 30 days, or Net in 45 days.

4. The customer enters the accounts receivable address.

5. The customer enters a contact person for the account.

6. The customer enters the PO number for the invoice.

7. The customer uses the note field to enter any additional information that may be required on the invoice.

8. The alternative ends.

If my customer has trouble understanding this use case, I would rewrite it to incorporate the steps of “Add Corporate Payment Information” into the alternative “The Customer does not have a customer id” in this manner:

Alternative: The Customer does not have a customer id
======================================================

1. The customer selects create account.

2. The system displays an account creation form.

3. The customer completes the name and shipping address fields.

4. If the customer is a corporate customer, do these steps:

4.1. The customer selects enter corporate payment information.

4.2. The system displays a corporate payment information form.

4.3. The customer selects the pay period, one of Net in 15 days, Net in 30 days, or Net in 45 days.

4.4. The customer enters the accounts receivable address.

4.5. The customer enters a contact person for the account.

4.6. The customer enters the PO number for the invoice.

4.7. The customer uses the note field to enter any additional information that may be required on the invoice.

5. Otherwise, the customer enters his or her credit card information into the payment fields, and a billing address (if different from the shipping address), into the billing address field.

6. The alternative ends.

 

Do you have a situation where you need to describe alternatives of alternatives? What approach do you use to structure your use cases in that situation?

Use Cases and Reports

Author: Geri Schneider Winters

I get my best ideas for these tips from you, my readers. This tip is a response to a question from Pete McNally on how to document requirements for reports and whether or not those requirements should be use cases.

Use cases are really meant for describing a process or task. If you are going to use a use case to describe a report, what you really want to describe is what job or task a person is doing when he or she creates and views a report. Why is the person reading the report? What will the person do with the information?

For example, assume someone wants to look at an application for insurance. The person wants to create and view a report of all the applications waiting for approval. Why? Because the person is reviewing applications to decide if they should be approved or not. So creating and viewing the report is one part of a larger use case – Determine Insurance Eligibility. A step of that use case would be to get a report of all applications waiting for approval. Another step would be to select an application for review (with any rules you have for which one to select, such as pick the application with the oldest filing date).

Here is a bit of an example to illustrate this concept:

Determine Insurance Eligibility
================================

1. The use case begins when the Evaluator asks the system for a list of all insurance applications waiting for approval.

2. The Evaluator selects the application that has the oldest filing date.

3. The system displays the details of that application.

4. The Evaluator enters the applicant’s age and medical information into the Health Calculator.

5. The Health Calculator determines the health index for the applicant and displays the health index to the Evaluator.

6. The Evaluator enters the applicant’s age, city and state of residence, number and age of dependents, and the health index into the Rate Calculator.

7. The Rate Calculator calculates the rate to be charged for the insurance.

…. There would probably be other steps here.

Alternatives
============
Application is denied

Now, what about step 1? What does that list of applications (report) look like? For that, you would use a report specification.

A report specification is a document that describes a report. In this document, you will describe the information that the user will enter into the system, how the report information is obtained or calculated, and what information is displayed to the user. You might also include a page with the design of the report, showing the various fields and the layout of the report. You can include any rules or algorithms that are used to create the report. You can include restrictions on who is allowed to generate or view the report, or indications as to when the report is run (for example, whenever needed, every night, once a week, once a month, once a quarter).

If there is no process that you can describe that includes creating a report, or viewing a report, then you do not need a use case at all. Just use the report specification to describe the contents of the report. It does not make sense to me to write a use case like this:

Create Quarterly Sales Report
=============================

1. The use case begins when the Accountant selects Generate Quarterly Sales Report.

2. The system calculates and displays the report.

3. The Accountant selects Save Report.

4. The system saves the report.

This use case provides me almost no useful information, and the little information it does provide can be put into the report specification with the other information about the report. There is no point to this use case, so why bother writing it?

Alerts and notifications may similarly fit better into another format.

Remember that not all requirements are use cases. Use Cases are great at describing tasks or processes – but not everything is a task or process. Reports are better described with a report specification document.

 

How do you describe reports, alerts, and notifications? Do you have a template for those types of requirements?

Do you see the usefulness of describing a task or process that includes creating and viewing a report?

 

Alternative Flows of Events

Author: Geri Schneider Winters

When you find an alternative to a use case basic flow, you have two different ways to handle it. One way is to put the alternative in the steps of the basic flow. That way of handling alternatives was described in a previous tip.

Another way to handle alternatives is to make a new section of your use case document for alternative flows. This section generally comes after the basic flow in your document. You write the basic flow to show the most common way of doing the use case, and the alternative flows list the other ways of doing the same use case.

I start by making a list of alternatives, using names and possibly brief descriptions. Let us assume we are working on a use case for a customer to Place an Order. While writing the basic flow, we assume that the most common form of payment will be credit card, so we write the basic flow showing that the customer is paying by credit card. I list the alternate forms of payment in the Alternative Flows section. Here is the example:

Place Order Use Case
Basic Flow of Events
====================

1. The use case begins when the customer selects Place Order in the order processing software.

2. The order processing software displays an order form to the customer.

3. The customer enters his or her name and address into the order form.

4. As long as the customer enters products, repeat these steps:

5. The customer enters a product code into the order form.

6. The order form displays a description and price for the product to the customer.

7. The order form adds the price to the order total.

end the repeat loop

8. The customer selects the credit card payment type on the order form.

9. The order form displays fields for the cardholder name, card number, expiration date, and verification code.

10. The customer enters credit card payment information into the order form.

11. The customer selects the Submit button on the order form.

12. The order form sends the information entered by the customer to the order processing software.

13. The order processing software verifies the information from the order form.

14. The order processing software saves the order as pending in the database.

15. The order processing software forwards credit card payment information to the accounting system.

16. The accounting system sends a confirmation to the order processing software.

17. The order processing software marks the order confirmed in the database.

18. The order processing software displays an order ID to the customer, and the use case ends.

Alternative Flows of Events
===========================
Customer Pays by Check or money order
Customer Pays by PayPal
Customer Pays by Cash
Customer Pays by some other method

Now at some point in time, I will need to add detail to the alternatives to describe how each alternative will work in my system. One way to do this is to copy the basic flow of events and change the steps that are different. I prefer the second approach, which is to just list the changed steps.

Below are the detailed alternatives for the use case. I am showing a couple of different approaches to writing the alternatives in the following examples.

Alternative 1: Customer Pays by Check
or money order
=====================================
In the Basic Flow of Events, replace steps 8-10 with the following:

1. The customer selects the check or money order payment type on the order form.

Alternative 2: Customer Pays by PayPal
======================================
Do the Basic Flow of Events, steps 1-7.

8. The customer selects the PayPal payment type on the order form.

9. The order form sends the order total and the company PayPal account name to the PayPal site.

10. The PayPal site displays a payment form to the customer.

11. The customer enters his or her PayPal payment information into the PayPal site.

12. The PayPal site sends the payment information to the order form.

The basic flow resumes at step 11.

Customer Pays by Cash
=====================
This is an error. We do not accept payment by cash.

Customer Pays by some other method
==================================
This is an error. We only accept payment by credit card, check, money order, or Paypal.

My basic rule for handling alternatives is this: If the alternative is short, just 1 or 2 steps, then put the alternative inline to the Basic Flow of Events as described in a previous tip. If the alternative is longer, then make a separate alternative flow of events.

How do you handle alternatives to the Basic Flow of Events?

Add alternatives to your existing use cases. If your company does not have a standard, try different approaches to see what works best for you.

 

Good Requirements

Author: Geri Schneider Winters

Consider all the different kinds of requirements you write – Use Cases, Business Rules, Security, Database, Performance, Usability, Reliability, Regulatory, “shall” requirements. Good requirements are well-defined. How can you determine if your requirements are well defined?

We often hear that good requirements are testable. This means you have some precise, unambiguous way of determining if the requirement has been met or not.

Of course, you can only define a test for a requirement if the requirement is well-defined! So we are back to making sure that the requirement is well-defined.

One approach is to use critical thinking.

Here is an example of a requirement:
“The system shall be easy to use.”

Think critically about this requirement. Is this a good, well-defined requirement? How will you test this requirement?

Think about that for a moment.

You can see that this kind of requirement is not testable in its current form.

First of all, a system that is easy for a person who has used computers for 10 years, may not be easy for someone new to computers. Is the system easy for someone with Windows experience, or easy for someone with Linux/Unix experience? What does “easy” mean? Does it mean easy to learn, or easy to use after you have learned it? Is it easy because everything is menu driven, or because everything is hot-key driven? Is it easy because it is like another popular software product? Is is easy because specific tasks can be completed in a specific amount of time? Is it easy for accountants to use because it is like other accounting systems? Is it easy for the general public to use because the interface is presented as a checkbook?

To make this requirement well-defined, you have to define who is using the system, and what that kind of person means by easy.

Often early in a project, the requirements will not be well defined. And that is OK at that stage of the project. But you can not produce code that meets the users requirements if the requirements are not clear and precise. The easiest way to make sure the requirements are clear enough to produce code from, is to ask “How will I test or verify this requirement?”

For use cases, many companies test the preconditions and postconditions and not the individual steps of the use case. They consider the individual steps to be guidelines to how the use case will work, not necessarily the actual precise steps. Other companies treat every step as a precise requirement. So the level of precision of the steps of your use case will vary depending on how the use case will be tested.

You might get the idea that you need to work closely with whoever is testing the code for the project. That is correct! Requirements and the tests for the requirements are closely related. They are so closely related, that some companies will ask the BA to write the requirements and test the completed product.

Some projects will start by having someone write the test cases first, then someone will produce the user requirements. This is called test-first design and is a very powerful technique for producting exactly the product the users want.

I know of one very large successful company that does not keep the project requirements once the tests for the project are written. They consider the requirements and the tests to capture the same information, so they throw away the requirements once all the tests for the project are written.

So test-first design is an approach to making the requirements clear, precise, and testable. Test-first design is a large part of the XP process, though is can be used with any process.

Of course, this assumes that the users know what they want! And that is often part of the problem. That leads to another technique for software projects – iterative development. The whole point of this technique is to solve the problem that the users do not know what they want.

You will write some requirements for the project, the requirements that seem to be the best defined. Then create code for those requirements, show it to the users, and ask if this is what they wanted. Typically some of it will be what the users want and some will not.

You will have meetings with your users to determine what to fix in the current product, and elicit another set of relatively well-defined requirements. Then build another version of the product and show it to the users again.

Iterative development assumes that some of the requirements are not clear, precise, and testable, and that they will not be until the users have seen the product and interacted with it.

Some iterative development processes are Rational Unified Process, Agile, and XP.

You can use techniques such as critical thinking, test-first design, and iterative development to improve the precision of your requirements, which will lead in turn to software that meets the needs of the users.

How do you make sure your requirements are well-defined?

Even if you are not responsible for the test cases for the requirements, try writing some tests for your requirements to see if the requirements are well-defined.