Detailed Function and Process Documentation | Requirements Analysis: From Business Views to Architecture


Team-Fly

	Requirements Analysis: From Business Views to Architecture By David C. Hay
	Table of Contents

	Chapter 4. Column Two: Activities

Detailed Function and Process Documentation

None of the techniques described above does more than identify activities, giving each a name and perhaps a number and description. Aside from exploding a process into smaller processes in a data flow diagram, there is no provision in these techniques for documenting in detail how an activity works. This requires a different approach.

Many processes are trivial on the surface: "record order", "issue work order", and so forth. The data flow diagram shows the information used and the information produced. A paragraph of text in the accompanying model documentation may be sufficient. Some processes, however, require more documentation in order to describe any algorithms used as well as any business rules that apply. Several techniques originally developed for documenting program logic are available for this. Among them are:

Structured natural language and pseudo-code text organized in a formal way
Action diagrams a kind of hierarchy of the steps required to perform the function
Decision trees and decision tables a way of describing the alternative steps that might be required.
Other hierarchical techniques, such as HIPO and Warnier-Orr

Structured Natural Language

Structured natural language ^[7] and pseudo-code are ways of describing specific processes. These typically describe the implementation of business rules, although until recently we didn't realize this. Pseudo-code specifically uses key words derived from programming and is similar in many ways to programming languages such as Pascal or C. Structured natural language takes a similar approach, but it relaxes some programming constraints to make it more readable for the casual user . Structured natural language is a more appropriate part of a requirements analysis. Carma McClure and James Martin described structured English in their 1985 book, Diagramming Techniques for Analysts and Programmers . Figure 4.26 shows an example of structured natural language. Note that there are four basic types of structure in this passage:

^[7] We in the United States grew up hearing that this was "structured English", but we live in a global marketplace , now.

Sequence a series of steps, one following after the other. No key words are involved. A step may be either an information processing or a physical step.
Condition the application of a test ("if") to determine which step should be taken. This is depicted by using the key words IF, THEN, and ELSE . That is, the structure is IF <condition> THEN <action 1> ELSE <action 2>.
Case a complex condition, wherein several alternatives are possible. Usually this is in the form IF <condition 1> THEN <action 1> ELSE IF <condition 2> THEN <action 2> ELSE IF ... END IF.
Repetition or iteration a specification that one or more steps are to be repeated one or more times. Repetition is of two types:
- R EPEAT WHILE operations are continued as long as a condition exists. The condition is tested before each iteration. Key words may be DO WHILE, REPEAT WHILE, or LOOP WHILE . For example, a structure might be DO WHILE amount received is less than 1000, THEN receive shipment END DO WHILE . The shipment that would take the total over 1000 would not be accepted.
- R EPEAT UNTIL operations are continued until a condition exists. The condition is tested after each iteration. Key words may be FOR, DO UNTIL, REPEAT UNTIL , or LOOP UNTIL . For example, a structure might be DO UNTIL amount received is greater than or equal to 1000, THEN receive shipment END DO UNTIL . In this case, the shipment of 200 units that takes the total to 1100 would be accepted, since the check is not done until after it is received.

Figure 4.26. Structured Natural Language.

graphics/04fig26.gif

Carma McClure and James Martin cite a set of rules for constructing structured natural language descriptions:

Format

The structures are indented to show the logical hierarchy.
Sequence, condition, case, and repetition structures are made clear.
The sequence structure is a list of items where each item is placed on a separate line. If the item requires more than one line, continuation lines are indented. The end of an item is punctuated with a semicolon (;).
Blocks of instructions are grouped together and given a meaningful name that describes their function.
Comment lines are delimited with a beginning asterisk and a terminating semicolon.

Key Words

Key words are used to make the structures clear: for example, IF, THEN, ELSE, ENDIF, FOR, REPEAT WHILE, REPEAT UNTIL, END REPEAT, EXIT.
Key words are used for logic: AND, OR, GT (greater than), LT (less than), GE ( greater than or equal to), LE (less than or equal to).
The choice of key words should be an installation standard.
The key-word set may be selected to conform to a particular fourth-generation language, but they are still language-independent descriptions.
Key words and names that are in the data dictionary are capitalized; names of program blocks are capitalized; other words are not capitalized.
End words such as END IF, END REPEAT, and EXIT are used to make clear where the structure ends.
Parentheses are used to avoid AND/OR and other ambiguities [Martin and McClure, 1985, p. 170].

Within these constraints, the wording should be chosen to be as easy as possible for end users to understand.

With all due respect to Ms. McClure and Mr. Martin, exception could be taken to Rule 7. In the interest of making the text as comfortable as possible for nontechnical people, the logic key words ("greater than", "less than", etc.) should not be abbreviated. It is arguable whether or not any of the key words should be capitalized. The sentences should certainly be as close as possible to common natural language sentences.

Action Diagrams

Ms. McClure and Mr. Martin also show an action diagram (not to be confused with UML's "activity diagram") as a way of continuing the function-hierarchy idea into the workings of an activity itself [Martin and McClure, 1985, pp. 183209]. The sequences, conditions, cases, and repetitions described above for structured natural language and pseudo-code can be represented as a graphic hierarchy: The statements of actions are listed sequentially with bars to indicate nesting, loops , and branchings of various kinds. Figure 4.27 shows a sample action diagram.

Figure 4.27. Action Diagram.

graphics/04fig27.gif

In the diagram, a simple bracket surrounds groups of steps to be considered together. The steps to be performed for each response to an IF statement constitute a special case of bracketing such groups of steps. In that case, the bracket is divided between the steps to be performed if the statement is true and those to be performed if it is false. In this case, the bracket points to the IF, ELSE, and ENDIF statements. Similarly, the bracket points to each element of a CASE structure.

Loops are represented by a thickened bracket with a doubled line at the top, pointing to the DO or FOR statement.

Bracketed groups may be nested inside each other. This provides a hierarchical representation of the steps.

Exits are shown by an arrow pointing to the left with the arrowhead outside the level being exited.

Decision Trees and Decision Tables

Like the flow charts popular in the 1950s and 1960s, UML activity diagrams may include logical tests and branching. Data flow diagrams and IDEF0 diagrams, on the other hand, do not show branching logic. In these cases, for example, after process 1, either process 2 or process 3 may be performed, arrows are drawn to both of them without describing the constraints that cause one or the other path to be taken. Sometimes this can be mitigated by naming a process: "If it is Tuesday, then...." Sometimes the decision logic is much more important, however, and this deserves a model in its own right. This is particularly true when business rules are involved. Sometimes this logic applies within a process, and sometimes it applies to sets of processes.

A decision tree is simply a set of lines drawn to show the possible paths that may be taken, depending on various tests of values. The graphic allows you to represent each alternative value for a variable and map what is to be done next . The technique is actually much more powerful for problem solving than will concern us in this book. Howard Raiffa, in his 1968 book, Decision Analysis , describes the technique shown here, as well as kinds of problems in probability theory that the technique can be used to solve.

Figure 4.28 shows a sample decision tree, describing the decisions associated with ordering a book. Was it requested ? Has it been reviewed?and so forth. This example shows only "yes/no" decisions. More complex ones are also possible.

Figure 4.28. Decision Tree.

graphics/04fig28.gif

A variation on the decision tree is a decision table . This is a table representing a sequence of decisions to be taken in a particular evaluation. A set of conditions is shown on the left, with one row for each permutation of values for the decisions. A column on the right shows each resulting decision, based on the particular permutations in that row. An example is shown in Table 4.2. Each of the decision points is a column in the table. Rows are then established for each combination of yes and no answers to the decision point. In some cases, a question is not applicable because of the answer to the previous one. For example, if the librarian does not know about a book, it is meaningless to ask whether the librarian likes it. In such cases the cell is indicated by "".

Table 4.2. Decision Table

Has patron requested?	Has it been reviewed?	Was review positive?	Does librarian know about it?	Does librarian like it?	Order it?
Yes	Yes	Yes	Yes	Yes	Yes
Yes	Yes	Yes	Yes	No	No
Yes	Yes	Yes	No		Yes
Yes	Yes	No			No
Yes	No		Yes	Yes	Yes
Yes	No		Yes	No	No
Yes	No		No		No
No			Yes	Yes	Yes
No			Yes	No	No
No			No		No

Other Hierarchical Techniques

Other techniques for documenting program code could be used to document business logic as well. These typically represent a problem as a hierarchical structure. Best known are the "HIPO" (Hierarchical input and output) diagram and the Warnier-Orr diagrams. Each of these can represent either a data structure or a set of activities in hierarchical form. See the 1985 McClure and Martin book for more information.


Team-Fly

Top