This is post two of five that shares learning and insight gained during a recent consulting experience. If you read post one of this set, you will recall that I started work with a team that was struggling to understand a small set of requirements. They said they wanted a set of use cases to help them understand the requirements so that they could survey various COTS solutions to identify the best fit. After doing my preliminary research, I asked the team to share a sample of something that they consider to be a good use case.

I have been through enough consulting engagements that I know every team and every organization has their approach and their style of documentation.  So asking the client for a sample that they like, saves me the trouble of creating something and then realizing that they wanted something else.

The team provided me with a sample document, which contained the following details for a single use case:
  1. A use case diagram
  2. A flow of events (including a primary flow and an alternate flow) as a textual description
  3. Preconditions
  4. Post conditions
  5. Extension points
  6. Special Requirements
  This type of documentation may be applicable if in an environment where the team is doing original software development, but it did not provide value to a team that is trying to understand requirements and survey the market to find a COTS solution.  So I talked with the solution development team and we agreed on a hybrid artefact that included a use case diagram, a workflow diagram, and other details found in a traditional requirements document.

It is important to realize that the team I was working with is constrained by the project methodology required by the organization.  The team must apply a traditional waterfall approach to project management and solution development.  Thus, it was important that the analysis artefacts I created fit into that style.

To develop this document, I applied another combination of business analysis techniques. I am not fond of the traditional interview-document-confirm requirement cycle.  When time is of the essence, I prefer holding a workshop (60-90mins) with key stakeholders and we discuss, brainstorm, and confirm details regarding the requirement, while key stakeholders are present.  To prepare for this event, I created a PowerPoint presentation with the key headings:
  1. Statement of the Requirement – as defined in the requirement document
  2. Intent of the Requirement – as ascertained through discussion with the original requirement author
  3. Business Goal/Objective – a paraphrasing based upon 1&2
  4. Terminology – It has been my experience that terminology can be the point of most confusion between the business and IT development teams, or even between different business teams, thus it is imperative that a common definition be identified.
  5. Scope Clarification – related to 4. This is an opportunity to clarify what is in scope and what is out of scope for the requirement or the solution.

I prefer to use tables and onion diagrams to help confirm scope, because words can be ambiguous.

  1. Current State Description – how things work today. What limitations and/or challenges exist?
  2. Future State Description – the vision for how things should work in the future (at the end of the project)
  3. Assumptions – factor that is considered to be true, real or certain without any proof or demonstration. If the factor is proven to be false, the outcome of the project could be affected.
  4. Constraints – factor that limits or confines the method or outcome of the project
    1. Hardware, Software, Financial, Schedule
    2. Policy, procedures
    3. Legislation, Laws
  5. Stakeholders – an individual, group, or organization, who may affect, be affected by, or perceive itself to be affected by a decision, activity, or outcome of a project
  6. Actors – the individuals that will interact with the system
  7. Use Case Diagram – representation of a user’s interaction with the system.
The presentation was prepopulated with my understanding from the preliminary research and was presented to the workshop participants, in advance, so that they could review and prepare for the discussion.  At the meeting, we worked to confirm and clarify all the points in the deck.  As the conversation unfolded, I edited the content of the deck (in real-time) so that the stakeholders could see the updated content. I like the “edit in real-time” approach because it engages the stakeholders and gives them the confidence that I have understood them as they intended.

While some teams may employ real-time multi-edit tools, like Google Slides, in lieu of a meeting, I am not fond of this approach, because it does not facilitate conversation between the stakeholders.  While there is a place and value for tools that enable collaboration between physically and chronologically dispersed stakeholders, there is still value in enabling real-time communication (via conference calls and WebEx), because communication enables understanding of a shared objective.

Following the meeting, I published the updated slides on a SharePoint site so that all the stakeholders could see the final version and provide their comments/feedback. If the requirement warranted, I hosted a second workshop to discuss the workflows, business rules, and data requirements related to the requirement. At this time, I turned the bullet points from the presentation, into prose in a requirements document and supplemented the information in the deck with the following details ascertained during the process.
  1. Functional Decomposition Diagrams
  2. Workflows Diagrams – may be in BPMN or a simple swim lane depending upon the formality of the process and the organization. The workflow shows primary and alternate paths through relevant actors for the process.
  3. Business Rules
  4. Data Requirements – inputs, outputs, validation, format, retention, etc.
  5. Capability Matrices – just like the one described in post one
  6. Details Operational Requirements
  7. Non-Functional Requirements – criteria that can be used to judge the quality operation of a system, rather than specific behaviors
At this point the requirement document was turned over to the stakeholders and solution development team for review and feedback.  Circumstance did not permit a face to face walk through of the document, so I encouraged stakeholders to send their comments to me by whatever means they could.  I responded to their detailed questions regarding the requirement document and updated the information weekly until the document was approved. Thus, what started as a request to develop the use cases for eight high level business requirements resulted in seven workshops, one interview, seven presentation decks, and five requirement documents and great detail regarding a set of requirements that was once ambiguous.

One requirement was dropped mid-process and three requirements were merged into one document because there were three parts of the same process.

Stay tuned to post three for insight into elicitation of non-functional requirements