Functional Design - A Picture IS Worth 1K Words

“It’s the requirements, Stupid.” Let’s face it. Projects get obsessed, enmeshed, mired, off-track, and so many other things so early on....

Using Agile or Waterfall approaches, everyone’s trying to get to the end faster, and with hopefully better results. The thing is that many folks arrive at a deadline and then discover that they had differing opinions on what was supposed to be delivered and whether something is complete, or how complete it is. The billing disputes arise even as testing kicks off, solidifying and entrenching these expectation differences, threatening the success of the phase, the project, and the relationships.

Often all sides go back to the “requirements” documents and “design” documents to compare against what’s been delivered. The purpose:

• What’s in scope and what’s out of scope – hey, what’s “scope” go to do with it anyway?
• What’s a change request – do we have change requests? Where are those little buggers?
• What’s a bug and what’s an enhancement – does this even matter?
• What’s a missed requirement – can I say it’s your fault?
• Determine whether the expectations as documented have been met or could be construed to have been met – time to bring in your most conservative BSAs and Developers to “interpret” the constitution...I mean the requirements and design docs
• If there’s time to fix any of this mess...and keep the relationships on track and stable

In many projects these documents are vague, out of date, misunderstood, and more. Most were never read, though they had many contributors and lots of meetings around them. They were created as a necessary step in the process and signed off.

They are created as necessary evils, artifacts, out of date as soon as they’re published, and inaccurate and incomplete from the start.

No wonder there were many and varied disconnects between expectations and generations of Word documents generated on the way to build and thereafter. The documents stayed static. The code was dynamic. There were demos, emails, meetings, phone calls, and hallway conversations that all impacted what was built and why, and all while those requirement documents collected digital rust.

Everyone’s busy inventing new formats for words as if it's the formatting that's going to make the requirements gathering effort yield better results. There are use cases, atomic use cases, RTMs, Business Requirement Documents, and a whole smorgasbord of document templates begging to be filled out.

What we’re missing is pictures, good old-fashioned diagrams. For every process, for every flow or subflow, you have a set of tasks to accomplish and an order in which they must occur. You have to identify the timing, the delays, the sequences, things that happen in parallel, the dependencies, and so on.

The more people stare at words, the more they write words, the more words there are. People fret about wording decisions and conditions in the negative or the positive, and so on.
Note also that document writing is generally “best” a solitary endeavor. It doesn’t lend itself easily (or efficiently) to collaboration. Sure, you can all gather around your internet meeting site and watch someone type while people shout, go for coffee, text one another, etc. Collaboration, inspiration, creativity, team-building and more aren’t fostered typically during that typically fragmenting and boring process.

What can foster creativity, participation, interpretation, and a fresh look is drawing pictures – mapping the process.

It’s so much easier to share the marker on the whiteboard or the pen on the tablet PC than to turn over the “driving” (I mean typing) to someone in a Word document complete with formatting, auto-generated section numbers, and more. ;-)

What you can’t see for all the words is what’s not there, and whether things are really in the right order.

You can’t tell how one document connects to the other, if there are common processes, common attributes amongst objects, if you’ve got all the actors accounted for, and so on.

What you need are pictures, diagrams to describe your business process, the BUSINESS FUNCTION.

The diagram below is from one of our favorite customer projects. It depicts about 50% of the actions that must occur before rendering the next screen (literally decisions and data that must be gathered between 2 screens).

Translating a lengthy text description of a process into a drawing forces you into an order. One box goes first, another goes second, and so on. Inevitably you are forced to connect things (using arrows generally) as you describe the process beginning to end. As you read a paragraph, page, or set of bullets, it finally dawns on you: You have no idea in what order these things must occur given the description. You aren’t even sure what happens AFTER these things take place, or before. In fact, you can find entire missing paths by discovering that you know what happens when a decision is true, but not what happens if it’s false. Voila! Flaws in the documentation are revealed quickly, effectively in ways that a 28^th (don’t laugh they do happen) revision of the Word document never would.

Note also that it’s far easier to recognize patterns in images than in words. You start to recognize common processes, actions, when you realize you’re drawing them again. Remember with words people can vary them enough in specific word choice and order so as to disguise repetition of various things. Pattern recognition gives you the chance to lift up and get multiple common items visited together, corralled for detail and design.

Pictures can reach people that words don’t.

Here’s something else to consider: not everyone’s primary or best method of communication is verbal or written. A third or less of your clients and TEAM MEMBERS are reached better by a different communication method.

The lesson: PICTURES and WORDS will reach a far broader audience, and they will illustrate the process far more effectively and efficiently if used together. It’s really easy to communicate questions, issues, etc. when you can literally SHOW it to someone without making them READ and PARSE dense text.

With a flowchart, you can point to something and ask, “What happens here?”

Pega and DCO make a stab at this, but note that these days you have to break large processes down into “atomic use cases” before you can get them into the system. You have to get your application defined inclusive of the atomic use cases (using the Application Profiler) BEFORE you can build a single flow rule. That means you’ve already identified all your processes, all the steps, and all the common processes, etc. before you’ve generated a single application rule.

To get your use cases broken out at any level, let alone the atomic level, you’ve got to define the process. It’s right there that diagrams, flowcharts, process maps can really ease communication and cut right to the heart of the matter.

Functional design makes it possible for the business to look at a chart (or a series) and say “Yes, that’s what we want the system to DO,” and sign off. Requirements documents, textual descriptions, can capture the details, and also the “non-functional” requirements. Wireframes, and other tools can describe the look and feel of the desired user experience.

Note also that it’s really easy to show scope creep in a diagram. You can literally say, “This process was 1 page when we diagrammed it and it was signed off. Now it’s 3 pages, and the steps are in a totally different order than built.” Ah. How many pages of a MS Word document, and the various email threads, and non-existent meeting notes would one have to read to identify the scope of the changes and the ramifications for a Senior Manager with 15 minutes to consider your change request?

From functional design and requirements documents the technical design can flow. The technical design will design the code solution, how the system will function technically. It should not be confused for the functional design – defined in business terms and steps.

Get the right design in front of the right audience.

Just as business users should not be required to evaluate technical design – to say “Yes, this should be custom Java”, technical consultants should not have to parse a myriad of dense documents to SEE what the business processes are that must be enabled, to see what the system should “do” when it’s completed. Functional design should let your LSA and technical consultants digest quickly what a process does and literally SEE whether various components are reusable, common, already existing in the framework, and so on.

The next time you’re bogged down in a meeting about requirements, think about whether you should be working together, collaboratively, over an image of the process and then break that out for detailed description and design, instead of debating endlessly whether section 5.4.3.2.1 is correct as stated.

As they say, a picture is indeed worth a thousand words.

Coming soon will be a follow-up article discussing how to incorporate these tools into an iterative project. Stay tuned.