To continue reading for free, register below or login
To read more you must become a member of SearchSoftwareQuality.com
Very good question since reports seem to be a primary focus of many applications, new or existing.
First, let's think about what a report really is and what a use case is intended to do. A report is a collection of information that can be sliced, formatted and delivered in all sorts of different ways (paper, online and so forth). A use case is a simple but powerful technique which exposes what the user has to be able to do (with the application's help, of course). So, a use case might identify a user task, such as "view customer information," which could eventually be implemented as a paper report and/or online report.
While I am a big fan of the use case technique because it focuses on the user, effective requirement definition takes more than one approach. There is considerable information about a report that is not conveniently captured in a user's request to "view customer information" (use case). You might think of this information as metadata about a particular collection of information. For instance, you probably need to capture a report definition, provider and receiver, delivery frequency, trigger(s), criteria for filter(s) and other things that need to be determined ahead of time.
Now, having to deal with all this additional report information does not take the use case technique off the table, but it does emphasize that just describing the user task, "view customer information," is not sufficient. A common way to document reports is to create a report definition template to capture this descriptive information, but this approach does not facilitate looking across a collection of reports to spot something missing or inconsistent or to discover patterns that might help consolidate. First, let me share two techniques I have used: a report use case pattern and a report definition matrix. In the Summary, I will apply these two techniques to the question at hand.
Report use case pattern
I am always looking for patterns -- patterns in words, patterns in steps in a process. About the same time I realized that a report was really just a collection of _______ information (you fill in the <blank>), I also realized that when a user asks to "view _______ information" that there are some typical steps. This "ah ha" quickly prompted me to define a pattern for any "view _______ information" use case. I found that the pattern was quite simple, whereas my previous thought that I had to capture all the possible combinations was daunting. (As it turns out, documenting all the possible combinations would not be all that helpful.) Keep in mind that the pattern below is a starting point intended to bring simplicity and consistency to the steps of this type of user task.
"View _____ information" pattern
| Step |
Description |
1. User requests "view _____ information" action.
|
"Request 'view _____ information'" is the ability to ask for _____ information.
|
| 2. System provides categories of _____ information requesting selection. |
Request selection of one and only one of the following categories of information: |
| 3. User selects information category. |
Select one and only one of the following categories of information: |
4. System determines viewing options based on selected information category.
|
"Determine viewing options" is the ability to conclude which way the selected information category can be presented.
|
| 5. System provides viewing options requesting selection. |
Request selection of one and only one of the following viewing options: |
| 6. User selection viewing option. |
Select one and only one of the following viewing options: |
| 7. System provides selected information category using selected viewing option. |
"Provide the selected information category using the selected viewing option" is the ability to present the selected information in the requested manner.
|
Report definition matrix
The report definition matrix below took shape after a number of general, often circular, report discussions. As you will notice in this example, the information about the report is categorized in collapsible columns (Hint: Data…Group) in an Excel spreadsheet. A more sophisticated approach could be used if you had other tools at your disposal, but the same principles of grouping information and having selectable choices can apply whatever method you use.
Take a moment to just glance at the types of information captured and note that each report is uniquely identified.
Now, let's expand each section of this report definition example. You will notice in the DEFINITION and PROVIDER-RECEIVER section that some columns have a list of valid values (Hint: Data Validation…List to identify the permissible values in an area not included in the Print Area). As this particular report definition matrix matured, these lists matured.(Click the picture for a larger view.)
Note below that the report data CONTENT is only referenced because, in this situation, there was already a group and a mechanism (Report Data Definition) to list the specific data needed for a report. Oddly enough, this group did not have a need to know who the report was for or its purpose. Also note the different aspects of DELIVERY.(Click the picture for a larger view.)
In the FORMAT and CRITERIA sections, some of the columns cross the boundary between describing what and how. When defining a new report, the requirements should document that the format must follow accepted standards, but they do not need to specify if the orientation is landscape or portrait. When documenting an existing report, you already have this design information. Ask yourself if this information would be helpful. If the answer is yes, then capture it but recognize this is report design information. Also notice that some of the CRITERIA information, such as the filters and sorting, provides the viewing options referred to in the report use case pattern.(Click the picture for a larger view.)
The last sections for DEVELOPMENT and COMMENT definitely reflect the situation from which this example was drawn. There was a need for some new reports, but many of the existing reports were either good as is or needed some modification. Since this matrix was to be used to help with estimating the work effort, the DEVELOPMENT columns were added. And, of course, there always needs to be a place to COMMENT, especially when a matrix such as this one has not fully matured.
Summary
Finally, I suggest you look beyond your immediate assignment because the existing application documentation you are creating needs to be useful. Knowing how this documentation will be used is, of course, the only way to really determine its potential usefulness. Apparently, this documentation you have been asked to do is not going to be used to develop a new application since one already exists. However, some potential ways to utilize these use cases and related documentation, such as the report definition matrix, are to:
- Develop a user guide
- Train new employees
- Provide a basis for regression testing
- Have the requirements for a replacement application
For all of the above, capturing the "what" is essential and capturing the "how" is optional (see FORMAT section above for an example). If the requirements that you are capturing (and that is what you are capturing in a use case) are ever to be used for a replacement application, any "how" statements can introduce an unnecessary design constraint for the replacement.
With all this in mind, consider the following report documentation approach:
Make a pass at making the report definition matrix your own. Remove the parts that do not apply and refine the parts that are not quite right in your situation.
For each report fill out your report definition matrix or use it as a guide to asking questions. For those reports that are not to be specified, consider including at least a row that acknowledges their existence and provides a place to reference where more information can be found.
Name the report use cases "View _______ information." Before you make each report use case more than a name, ask yourself if the report definition matrix provides the report information needed for now.
- If yes, include the "View _______ information" use cases but put a reference to the report definition matrix in the body of the use case.
- If no, leverage the report use case pattern and the report definition matrix to provide all the necessary information about the user task and report meta data.
Whether the answer is yes or no, information should ideally appear in only one place and be referenced elsewhere if needed.
|
