Articles from March 2011

When developing requirements for a business process in which there are valid process variants, one usually describes the process variants as a behavior. When modeling these variants, it is useful to consider each aspect of a process that has variants, and isolate unique behaviors based on some decision framework. Both the distinct list of behaviors (behavioral taxonomy) and the attributes driving the decision framework (driver mapping) are important to the model.

The list of behaviors is important, because the words that identify each behavior become important words in the language used to describe your business process. When you talk about these behaviors, you all (technicians and subject matter experts) can use the same unambiguous terminology to describe the process.

Sometimes in the business process documentation, the language is about the steps and the business rules that govern each step. At a higher level of abstraction, we benefit from aggregating these business rules into patterns, or behaviors that have some cohesion around a small number of attributes or facts. When we observe these patterns, we can simplify the language around the business process, by naming the distinct patterns as specific behaviors, and identifying them with a business driver as observed in the attributes.

When we isolate and name the patterns as specific behaviors, we also can understand the data elements or attributes and values that drive the decision framework. This mapping of data elements and values to select a behavior is also part of the requirements, as it is important to ensure that all valid values for each attribute are considered in the behavior selection.

More complex processes may have several different aspects that are governed by distinct behavioral taxonomies, and isolating these taxonomies from each other is important. Sometimes when we try to render a single behavioral taxonomy that governs a process, and find that we cannot easily recognize the behaviors, we actually have a more complex case, where there are nested behavior variants, or we have non-correlated (independent) behaviors governing several aspects of a process. In these cases, if we isolate the individual lists or taxonomies of behaviors, then review against each other to determine whether relationships exist between taxonomies. Those relations can be classified as governing hierarchies (where available selections in one taxonomy are limited by the selection in another "governing" taxonomy.), or incidental constraining relations (where as it happens, the selection of a behavior in one taxonomy, either requires or invalidates one or more behaviors in other taxonomies, but those constraints are not imposed exclusively in any one direction between two taxonomies)

Clearly identifying the distinct behaviors of the business process, and the data elements or attributes that can be used to select each behavior supports a good requirements modeling practice.

Have you ever had the experience of having someone explain something new to you, and somewhere along the way, your brain replaced something new with something familiar? So when you went to the next step, to work on the new thing, you immediately became confused and either did the wrong thing, or did something that made no sense. You unknowlingly transposed something familar for something new without proving that they are the identical. Call it a synaptic misfire, or just mental laxiness, it happens with alarming frequency.

Transposition of the familiar is an antipattern of knowledge acquisition. In knowledge acquisition, one is required to assimilate new information. New information must be analyzed, and assigned to categories and taxonomies. The antipattern happens when you identify the category of a new fact, but transpose attributes of familiar facts from the same category onto the new fact, even when they are not really valid. The worst instances of this is when you ignore the new attributes, preferring the transposed attributes.

This is extremely common in learning new software development paradigms (languages, patterns, and related constructs) when the developer sees a logic construct, like an if-then-else or loop construct in a new language, and assume that it observes that properties of a similar construct in a more familiar language. For this reason, until the new language is completely internalized by the developer, it is good for him to be completely immersed in the new language.

The same thing is true of entities in a new business domain model. Our brain automatically pulls out the terms we recognize and substitutes familiar metaphors. When the metaphors in the new business domain differ from the familiar, those transpositions introduce errors or at minimum inconsistencies in the model.

This is an antipattern that can be avoided through diligence. Understanding the prevalence of the antipattern is the first and easiest preventative measure.

Another preventative is immersion – you immerse yourself in the new paradigm (what ever that is) and force yourself to unlearn everything else for a period of time, until the new paradigm sticks.

A third preventative is to engage others who have diverse backgrounds (and therefore familiarities) and collaborate with them to embrace the new paradigm together, holding each other accountable for adherence to the new.

The last and potentially most effective preventative is to engage someone who is expert in the new to assess whether you are "getting" it. This can be expensive if you end up hiring a trainer, or coach or bringing in experts from the outside of your organization.

Many times, when organizational management wants to implement transformation to new paradigm, this last preventative is the approach they take first. But this approach is limited when it is used to "push the paradigm" – all other approaches assume that a desire to assimilate the new paradigm is already in the resource who is trying to assimilate. Knowledge acquisition is by definition, a pull activity.

Software design is a process. It is a process of taking one abstraction – a business oriented model, and constructing a different abstraction – a technology oriented model.

Since there are many different technology paradigms, the technology oriented model differs based on the paradigms selected. The business oriented model differs by business, and the problem or value proposition. Part of every good design process is to decide how to represent or document each of those models.

For the most part, software design metthodologies have been selected because they help the developers represent the models that are in play, in ways that reflect the technology paradigms that are in use. Each methodology has commended some set of artifacts and sequence in developing, reviewing and revising those artifacts (e.g. Flowcharts, dataflow diagrams, uml class diagrams, data dictionary, data model, etc.).

Enter the antipattern:
In my experience, different organizations have used these methodologies and produced these diagrams with varying amounts of rigor. Somewhere along the way, auditors who are charged with proving that capital spent on software development actually resulted in a depreciable software asset decided that reviewing the artifacts of the software development life cycle (SDLC) were a good way to do this.

In public stock corporations, these audits are now required by law. Since the enactment of this law, known as Sarbanes-Oxley many large coprorations that engage in developing software products to be used as assets in the operation of their business, require that the documentation produced out of their SDLC are designed to pass these audits. Many of them have produced templates that are designed more to pass these audits then to help software developers capture the essence of the abstract models and prepare to build software.

When the developers who had less rigor in their design practice originally, are confronted with these document templates, their already ad hoc design process simply conforms to the template that they are presented with. This conformation of a process to a documentation template, without contemplating whether there is an appropriate methodology in place, or whether the template logically represents the essentials of the specific design being contemplated we have an anti-pattern.

Document driven design belies a focus on meeting audit requirements through our design documentation, rather than focused on articulating what it means to produce software capabilities. Similar antipatterns can manifest themselves in any aspect of our practice, where process compliance is more important that work product. Management's insistence on process compliance as a means to improve quality, moves us rapidly towards least common denominator solutions. However, it is inherently measurable, and easy to detect failures. It cannot, however, help you detect opportunity cost, or missed innovations, or other work product that was ignored, while maintaining process compliance.

Document driven design and similar template driven practice antipatterns often use the phrase "Best Practice" to rationalize their existence. But the tend to institutionalize a one-size-fits-all mindset, and with any best practice, what is best for some may not be suitable for all.

I am not suggesting that we eliminate design documentation, nor am I suggesting that we should not use document templates of some kind. Design doc is important both to clearly articulate design decisions we have made, and to help those who come behind understand how we got here. Templates are a useful product, for any repeatable process. However, templates must be aligned with the established repeatable practice, and if no practice is established, then all templates are simply taking the place of established repeatable practice. Those who create a document template should publish a process guide, to explain how their template aligns with a specific practice, or how it can be used by practitioners of alternate practices. The point of templates is to give someone responsible for documentation a leg up, or a head start. But often we are just providing an easy out, or an alternate version of chaos.

The next time you are confronted with a set of process documentation templates, ask yourself if you know how they align with the process you are performing. If you don't and are tempted to discern the process from the templates, then you are entering a template driven practice antipattern… proceed with caution.

When you read requirements, do you ever wonder "How will an end user get value from this?" or "What does the user do with that information?" or "How does this detail matter in the big picture?"

You may be missing some usage scenarios. Usage scenarios tell you why the user is doing something. Where use cases start with an actor, and describe a series of actions required to complete some unit of work, the usage scenario, starts with a goal and an initiator, then details the actions and outcomes.

Case Study:
A few years ago I was on a project where we had a requirement to build a Cash Balances report. Our requirements described the format and content of the report, as well as the criteria for initiating the report. We had all the information we needed to build the report, but did not understand the reason the report was necessary, since the cash balances were displayed in several other places in the system. When the analyst went to ask the user about how the report was used, he wrote the following usage scenario:

In order to ensure portfolio managers can have updated cash positions at start of day <goal>, every morning when the reporting system is available <initiator>, the administrative user will run the "Cash Balances" report <action>, then input the cash balance for each account into the portfolio management system <action>.

Understanding: the goal of this usage scenario is "in Order To…" – which has little to do with the report that the user runs. Wouldn't an interface be better? Why would I even build a report? We learned that the cash balances that we were looking for actually came from a different system than we thought, and were only important for updating the portfolio system. We also learned that this manual update process took about 2 hours every day, and delayed the start of trading for the business unit.

Outcome: We built a fully automated interface, at 40% of the cost of the report, and saved .25 FTE effort ongoing in the business unit.

Understanding the context in which a feature or capability will be implemented is as important as understanding how the feature or capability will work. Requirements without an understanding of the business context in some manner are incomplete, and often lead to poor solutions.

In this case, we learned that the current business process could be significantly improved for less cost then supporting the existing process. This is an opportunity that would have been missed if we had not taken the time (2 hours) to understand the business context of the requirement.

In authoring software requirements, there is very little room for embellishing prose. When I read requirements that contain embellishments like adjectives or adverbs, I often think that each embellishment represents a requirement that has not been completely articulated.

For example, when I read a requirement that has words like "robust", "complete", "performant", "responsive", or my favorites "user friendly" and "intuitive", my instant reaction is "What do you mean by that?".

Every one of these words in a requirement, should be qualified by one or more requirements that explain what it means to be robust, performant, etc.

The greatest likelihood is that all project participants will have opinions about what these words mean, but without qualifying them, each person is allowed to believe that they understand, without actually agreeing or coming to consensus.

I challenge you to read your next requirements document, and circle all of the adjectives or adverbs, and ask "What did the author mean by that?" That might be a great way to start a review for a draft of software requirements.