Explaining Processes and Finding Requirements
Processes are mechanical by nature, and lend themselves well to a rigidly structured explanation, though implementing a formal process can be detrimental, in that it limits the focuses and causes requirements to be overlooked.
The author indicates seven elements of a process explanation:
- Name and number - To identify the process
- Triggering Event - An indication of when the process is used
- Elements - A list of all entities (hardware, software, data, people) involved
- Actions - The series of events or steps involved in the process
- Results - The end state of the process, including all data outputs
- Success criteria - The desired result for which the process is implemented
- Requirements - The exact conditions that must exist for the process to operate successfully
Each of these elements can be high-level or specific. As stated previously, there should be a brief and general process description to give the reader a sense of the whole process, and more granular descriptions of each aspect to ensure precision and detail.
Process Name
The name (and often a number) identify the process. While this seems self-evident, the author mentions that there have been instances in which the lack of a unique name, or failure to reference a process by name, has resulted in chaos.
And so: give the process a unique name, make it prominent on all documentation, and ensure that it is used consistently when referring to that process.
Triggering Event
Another no-brainer that is often overlooked is the clear definition of a triggering event. If it is not well defined, the process may not execute, or may execute when it shouldn't. There's more information on specific detail (time, quantity, action, etc.), but it seems excessive and incidental.
Elements
The list of elements ensures that everything is in place, and can be used as a reference as systems evolve (if an element is altered or removed, you must know what processes it will impact). As above, it is critical to be comprehensive and precise. Of special importance is referring to other processes on which this process depends.
Actions
At its core, a process is a sequence of actions, which can be documented as a numbered list in the order of their execution. For each action, the author suggests a very specific format to ensure all the important information is documented:
- [Actor] [acts] [upon something] [to accomplish something].
Ditto the above notes about precision and detail.
Exception Handling
In addition to describing what out to happen under normal or perfect circumstances, the document should also describe what should happen when the unexpected occurs. Ideally, this should provide a smooth way to handle such instances, such that the "error" is known and can be corrected (or avoided). Worst case scenario is that something goes wrong, the process keeps chugging along, and no-one is the wiser until disaster occurs.
One of the most difficult tasks is discovering a comprehensive list of all possible exceptions: they are unexpected cases, and some of them may be unpredictable. However, they can often be discovered by investigating the underling assumptions in an action and asking what could possibly go wrong.
However, you can also overdo it: the documentation on exceptions can overwhelm (and sometimes subvert) the core purpose of a process. This is referred to as an "exception driven" process, and is often made overly complex.
Exceptions should not be included in a high-level overview, and how best to handle them in a detailed document depends on the amount of information.
- If exceptions are infrequent and easily explained, they could be documented in context (a highlighted, indented paragraph)
- They may be included as a section or subsection as a bulleted list;
- They could be described in greater detail in a separate document (suggested format: a table that indicates the condition in one column and the desired results in another).
Whatever format is chosen, the important thing is to ensure that they are easily distinguished from the main list of options, and that they do not get in the way of understanding the core process.
Results
The results of a process include not only the intended output, but also any other impact the process may have (incidental or seemingly inconsequential to the process itself). Fundamentally, a "result" occurs at any time data is affected (add/edit/delete).
Note that kicking off other processes should also be documented as a result, but the results of those possesses need not be documented (as they should be documented in the other process documents) unless they are of particular importance to the current one.
Success Criteria
The success criteria should begin with a brief and succinct statement of what should occur if the process is successful, then follows up with more specific details that can be used to measure whether the process was successful. Be especially careful about vagueness in the documentation of success criteria: they must indicate an outcome that is plainly evident and objective.
Requirements
Requirements provide an indication of what conditions are required to make each action in the process result in success. It's noted that requirements also help evidence exceptions (if requirements are not met, the process will fail). Again, be brief and precise.
Of importance is that there is "no harm" in creating too many requirements in early drafts, though it's important to review the requirements to remove those that are unnecessary (not strictly required) or redundant.
Of particular importance is that requirements are not actions (they do not describe the process), they are not results (they do not describe everything that might happen) and they are not exceptions (they do not capture everything that might go wrong). They describe the conditions that are required for the process to succeed, and nothing more.
Language in Requirements
There is a widespread preference for a formal writing style that begins each statement with "the system shall" followed by lengthy and complex statements. This is wordy, monotonous, and vague, and they often include extraneous information (exceptions, conditions, etc.). The author recommends short sentences with stronger verbs, shunning shall/will and other versions of "be."
Numbering Requirements
Requirements are often numbered for reference. The number can be useful if it corresponds to the process and to the step (action) within the process to which it pertains. Alpha codes are also used to indicate the type of requirement (FR for "functional requirement," at. al.)
Dealing with Ancillary Requirements
While developing the functional requirements, other requirements will surface, and the author describes how to deal with them:
A data requirement describes a piece of information necessary for a process to execute. These are often discovered while writing functional requirements, and can be very lengthy. The author advises shunting these to an appendix and referring to them from the main (functional) requirements.
A business rule documents the needs of the business to follow a certain process (for operational, accounting, or regulatory reasons). As with data requirements, they should be documented elsewhere for reference, but not clutter the functional reqirements
There will also be nonfunctional requirements, in place to communicate information about the process to others (management, vendors, stakeholders etc.) Shunt these to a separate appendix as well.
Structure of Requirements Documents
Numerous document structures have been devised over time for communicating requirements in a standard way. Standardization is lauded for facilitating comparison among projects, enabling common practices among all project teams, or forcing the author to document all aspects. However, a rigid format becomes an obstacle to reading comprehension and may result in the loss of important information (if there's "not a column for that," it isn't recorded, even if it's very important).
The author asserts that "old-fashioned prose with a few well-chosen headings" can be easier to read and write than a rigid tabular structure. It may be necessary to provide a structured document to certain audiences (programmers, for example, work well with a table of exceptions including columns for "if" and "then" and other conditions) - but the core requirements document should be more readable for a wider and less-specialized audience.
The suggestion seems to be to write prose first, and schematize it into structured documents for the audiences that need them.
Using Diagrams
A lot of words, but the author's advice is that a diagram can be used to illustrate a concept that is described in text, but it should not substitute for it. (Again, write the prose first, determine where diagrams are needed afterward.) Some of the worst, least understandable, and ultimately unsuccessful process documentation consists almost entirely of a stack of diagrams.
Using Summaries
A process document of any length will begin with an executive summary, which gives the reader a general sense of the document (and in some instances, can provide adequate information for those who need only a "big picture" of the project).