This article describes Phase 3 of the Business Analyst Designer Method – Design.

Overview

Phase 3 (Design) is all about specifying the detailed functional design for the feature. Most of the hard work has already been done in the Define phase, and now it’s just a case of filling in the details.

The following diagram illustrates the inputs and outputs to Phase 3:

The following diagram illustrates the individual steps in Phase 3:

There is nothing especially novel about the Design phase of BADM – this is all pretty much standard IT system functional design work. The functional design pivots around the system functions, specified as acceptance tests, in a form very similar to (written) use cases (or, if you’re more familiar with agile terminology, BDD scenarios). For some features, it might also be appropriate to specify changes to the business processes that wrap around the IT system functions.

Before diving into the details below, it’s worthwhile reading this article first for a general discussion on what does and doesn’t go in a functional specification.

Phase 3 Inputs

Phase 3 starts with a feature that has already been scoped and sized, the details having been captured in the Feature Scope Definition, as explained in BADM Phase 2. The team already has a good idea of how it is going to work, and all that remains is to fill in the details.

Functional Design Document Template

Over time, I have experimented with various styles/formats for FDDs. In particular, I have previously described a textual format and a graphical format. Most recently I have been using the textual format, largely because they are quicker and easier to produce, but also because we are able to load them into our test tool (Quality Center) so they can be used directly as test scripts by the test team.

Hence the “official” BADM FDD template uses a textual format. It’s a spreadsheet, not a traditional document, for all the reasons explained in the above article.

You can download the BADM FDD template here:

• BADM FDD – Fxxx – Template v1

Step 3.1 – Write Overview

The first job is to write down (or, preferably, draw) an overview of what the feature is delivering. Often, a context diagram is ideal, showing the system as a box, the relevant human actors as stick men, any relevant external systems also as boxes, and then labelled lines showing who is interacting with whom, or what, and what sorts of data is flowing between them. Usually I just cut & paste an appropriate diagram from the FSD. Job done.

The overview goes, unsurprisingly, on the “Overview” tab of the FDD. The Overview tab also includes other summary information for the feature, including links to any supporting documents e.g. UI designs or data definitions.

Step 3.2 – Specify Business Processes

All features deliver a business process change. Mostly we are concerned with IT system change, and the business processes that fit around the system functionality are usually self-evident. But sometimes the changes to business processes are non-trivial, and it’s worth thinking them through and capturing them.

Hence this step is optional and only needs doing for non-trivial business process changes.

BADM doesn’t have a huge amount to say about this step, other than to recognise that it exists. And there isn’t a template either, but the obvious thing to do is draw some flowcharts, probably with swimlanes. There’s plenty of advice out there on how to do this.

Step 3.3 – Identify Functions

The next step is to specify what the system does. The key word here is “does”. This is about describing the actions the system performs. Given that a system usually perform actions in response to actions performed on it by external actors (be they humans or other systems), then what we are interested in are the interactions between a system and its users.

I’ve used the term “functions” although there are other terms in common usage, such as “use cases”, “behaviours” or “scenarios”. As far as I am concerned, they are all synonyms of “functions” – they are all about describing what the system does. I use the terms interchangeably below.

In BADM, a feature consists of one or more functions (or scenarios).

Each function (or scenario) is a single sequence of actions (an interaction) that can occur between the system and its (human or system) actors under specific conditions. Typically the actor is trying to achieve some objective (log in, search for data, update data, perform a calculation etc.).

In use case speak, a function (scenario) is a single use case flow – be it a main flow or an alternative flow. In BDD speak, a function is a single given-when-then scenario, or a single acceptance test (see this article for a discussion on the striking similarities between use cases and BDD scenarios).

The full set of functions for a feature together specify what the system does under all relevant conditions for that feature. In use case speak the function set covers all use case main flows and alternative flows that are in scope for the feature. In BDD speak, the function set covers all scenarios, or acceptance tests, that are in scope for the feature.

Specifying functions is typically a two-step process which tends to iterate:

1. Identify functions
2. Specify function details – which often results in more functions being identified

Identifying functions is as simple as making a list of the different flows/scenarios/tests that need to be described. Identifying all functions up front is tricky. It’s easy to identify the main flow (“happy path”) functions, but harder to spot all of the alternative flows. The alternative flows tend to arise once you start specifying the steps of the main flow functions.

Each function is given a unique ID e.g. “F101-001” is function 001 within feature F101.

The list of functions is entered into the “Functions – Summary” tab in the FDD.

Step 3.4a – Specify Functions

Specifying a function means writing a sequence of steps that describe the interaction between the system and one or more (human or system) actors. Each step is either a user action or a system action. I’m not going to describe this activity in great detail, because there’s already a whole book on this topic:  Writing Effective Use Cases by Alistair Cockburn.

But I will give an example to illustrate the point:

Function F101-001: User Logs In Successfully

1. User requests to log in
2. System asks user to enter their username and password
3. User enters username and password
4. System verifies that the username and password correspond to a valid, active user
5. System logs user in and displays the home page

Note that step 4 implies other functions (alternative flows/scenarios) – what if the username and/or password are incorrect? What if they correspond to an inactive user (or a locked account)? But unless you’re really on the ball, you only discover these alternative flows when you write down the steps for the main flow. Hence the process tends to iterate.

That leads into another topic: collaboration. The Business Analyst Designer is unlikely to discover all the scenarios alone. And even if he does, he won’t always know how the system should behave in each scenario, or what technical limitations there might be. Hence he needs to collaborate with:

• The Business Owner
• Any relevant Business SMEs
• The Technical Owner
• Any experienced testers that happen to be available

You might think that you don’t need to involve testers in specifying a system’s functions. But you’d be surprised at how good they are at spotting functions – particularly alternative flows – because they are experienced in thinking about edge cases and how to break a system with unexpected inputs.

Many agile practitioners have recognised the importance of this collaboration and a phrase has been coined to describe it: Three Amigos. Some people refer to Three Amigos as a specific meeting to either identify or specify functions, but others refer more to it as an ongoing collaboration throughout the delivery lifecycle. Either way, collaboration is important.

The function steps are entered into the “Function – Detail” tab in the FDD. Note that this tab auto-copies the summary info for each function from the “Function – Summary” tab.

Step 3.4b – Specify Data (Optional)

Most IT systems store data. Therefore, in specifying functions, sooner or later you are going to stumble upon some data. The vast majority of functions either store data to be retrieved later, or else retrieve data that was stored earlier, or do a combination of both. In order to tie storage & retrieval functions, you (probably) need to specify the system’s data store.

In most systems, the data store is a relational database, but in these modern days of lightweight mobile devices, it might well be something simpler like an XML file. Either way, a system is normally storing entities, the attributes of those entities and also the relationships between the entities.

So you might need to specify, for example, that a Person has a First Name (max 20 characters), Middle Name (max 20 characters), a Surname (max 40 characters) and a Date of Birth (a date).

And that a Person can have one or more Addresses, and that an Address consists of Address Line 1 (max 50 characters), Address Line 2 and so on.

In my experience, there are two ways of specifying the data model for a system:

1. Do it
2. Don’t do it

Option 2 works surprisingly well. You can often specify the data model implicitly by specifying the functions (and associated user/system interfaces) that either store or retrieve the data. For example, if you specify a user interface to create (or amend) an Address, and that UI has 5 address lines, each with max 50 characters, then you can pretty much work out what the underlying data model needs to look like.

However, that does make life trickier when you come to specify the various functions that retrieve the same data. Without a data model you are left unsure as to whether Address Line 1 is a free format field or can only contain a house name or number, or whether the postcode/zip code is always held in Address Line 5. It also means that you might not think holistically about the entities that your system is to store up front, with costly re-factoring required later on. But if you’re running XP with automated testing and continuous integration, that might not be too much of an issue.

In general, I’m an advocate for producing documentation that is barely sufficient, so on balance I’d recommend Option 2 where possible.

Accordingly, the BADM FDD template doesn’t currently include a template for data modelling, largely because the projects I’ve used it on either haven’t specified a data model explicitly, or else have used formats that were very specific to the system in question. Plus maybe I want to encourage you to see if you can manage without one. So I’ll leave you to develop your own data model format, or not as the case may be.

Any data spec you create should either be included in the FDD (as an extra tab) or referenced from the FDD (include a hyperlink on the Summary tab and also in the References column for the relevant steps on the Function – Detail tab).

Step 3.4c – Specify Interfaces (Optional)

Humans and other systems interact with a system through its interfaces – user interfaces and system interfaces. Some functions are entirely internal to a system, with no inputs or outputs, but most involve interactions with external actors.

You either need to specify what those interfaces look like, or else leave your development team to work it out for themselves/guess. The second option might be viable if you think you can trust the dev team well enough and/or if you are adding functions to an existing system with an existing look and feel. In particular, if you are using BADM within an iterative lifecycle, you even have the ability to improve on the dev team’s guesswork in a later iteration.

My experience, though, is that things generally go better if you specify the user/system interfaces up front.

There are a number of different ways you can do this, including:

• For user interfaces:
  • Build a prototype e.g. HTML mock-ups
  • Draw wireframes e.g. using Visio or Balsamiq
• For system interfaces:
  • Build an example interface file (if it’s a file-based interface)
  • Draw up a spec, including both syntax and semantics.

Your interface specs can either be included directly in the FDD (as extra tabs) or in separate documents, referenced from the FDD (include hyperlinks on the Summary tab and also in the References column for the relevant steps on the Function – Detail tab).

Step 3.5 – Agree Functional Design

Once the function design is complete, there is one final step before it is really complete. That is making sure everyone agrees on what is to be built.

Now, because the Business Analyst Designer has been collaborating with the Business Owner and the Technical Owner throughout the Define and Design phases, you might think that there is no need for an explicit agreement step. And you might argue that going through a formal approval process creates an unnecessary delay in proceedings. And you might also say that on an agile project with short iterations, it doesn’t matter too much if the built system isn’t perfect on the first attempt, because there is the opportunity to fix/improve in a future increment.

And in some cases you’d be right. But in many cases, my experience is that some form of lightweight formal agreement on what is to be built is worth doing.

Here’s what I’ve noticed.

Designing software involves making decisions. Often it involves making tricky decisions, with various trade-offs between quality/usability and cost/time. Making decisions involves thinking, and thinking is hard – it makes your head hurt. Many people (especially non-IT people) will try to avoid thinking if at all possible, preferring instead to do non-thinking tasks like attending meetings, replying to emails or drinking coffee. And yet something has to be built, and it costs money to build software, so decisions must be made.

Formal agreement forces stakeholders to commit to building something. It’s a way of saying, “right, are you sure this is what you want, because next week we’re going to start building it, and these IT guys are expensive, so we’re going to spend quite a few dollars”.

For agile projects, where change is anticipated (embraced) the commitment is slightly different. It’s more like this: “right, is this really your best guess at what you want, because even though we know we might have to change it later, we are still going to burn some dollars building something next week”. I’ve heard stories of agile projects churning as stakeholders constantly change their mind on what they want, and I suspect the problem has something to do with being too willing to build any old damn thing without thinking hard enough up front.

For me, on most projects, the pros of formal agreement outweigh the cons.

It’s also useful to get formal agreement from the technical team. This is forcing them to say, “yes, I’ve looked at this, and it is feasible”. Plus, by getting both “sides” to agree, you have effectively made a contract (which is also especially useful if the build is being done by a 3rd party).

So, in BADM, the Business Analyst Designer obtains a formal approval for the FDD from two people:

1. The Business Lead
2. The Technical Lead

I’ve used two different methods of approval, depending on circumstances:

1. Written – the Business Analyst Designer circulates the (draft) FDD by email for approval and the approvers respond.
2. Verbal – the Business Analyst Designer discusses the (draft) FDD face-to-face with the approvers (either together or separately) and asks them to confirm they agree with what is to be built. There is then the option to minute the agreement afterwards.

Option 2 is a good way of avoiding the inevitable delays and nagging associated with e-mail approvals.

Conversely, Option 1 is the best way to force stakeholders to really think before they commit. Writing “approved” and clicking “Send” really focusses the mind!

Either way, once the Business Analyst Designer receives the approvals, he then creates an approved baseline of the FDD and circulates it to all interested parties. See this article for further details on document version numbering.

Phase 3 Outputs

The outputs of Phase 3 are:

• An (approved but lightweight) Functional Design Document
• Optionally, a Business Process Design

Next Steps

Once the FDD is approved, the feature is ready to go into build. At this point, the feature might already have been scoped into an Increment, or it might not. In an ideal world, the FDD has been completed prior to the increment starting, so the feature sits waiting for the increment to start.

Once build starts, issues with the FDD will arise and will need to be addressed – usually meaning the FDD has to be updated. Keeping on top of FDD updates is a good idea because it keeps the contract “true”. I tend to find there are two types of updates:

1. Clarifications – where there is ambiguity in the specification, or a plain mistake. I update FDDs with clarifications without going through any formal (re)approval.
2. Changes – where something more serious is wrong and requires a re-visit to the spec with the relevant stakeholders. In this case, I update the FDD and get it re-approved. Because there are only two approvers, this isn’t generally too much trouble.

The FDD is also used for testing. The functions (scenarios) in the FDD double up as acceptance tests – hence there is no need to write separate UAT test cases. Your test team might want to create additional test cases for system testing – testers seem to want to write more tests than strictly necessary -but at the end of the day, the acceptance tests are the acceptance tests. If they pass, then the feature is “done”. If the system does something “unexpected” under other conditions, that just means you missed a scenario.

So the FDD is pivotal to the UAT for the feature (or the Sprint Review if you’re talking Scrum). The Business Analyst Designer co-ordinates the UAT session and gets one of the developers or testers to demo each function (scenario) or, even better, invite the Business Owner to execute the functions themselves.

Any issues that arise during UAT fall into one of two camps:

1. The system doesn’t work as per spec – in which case we have defect which has to be fixed before the feature can be declared “done”.
2. The system does work as per spec, but the Business Owner wants something different or something more. This then becomes a new feature to be added to the Product Backlog.

Once the feature is “done”…well, it’s done. Time to move on to the next one!

Feedback

I’ve probably missed a whole load of detail. So if you have any questions or observations, please leave a comment and I’ll try to fill in the blanks.