Rules to Better Specification Reviews - 21 Rules

You would never build a house without getting an architect to create a plan first. Usually, a specification process is done with the client before beginning work on a project.

As expected, it's not realistic to fully understand the complexity of a client's system, and give an accurate estimate after one brief meeting. For most business solutions, a few days are needed to obtain and document the requirements of the project’s stakeholders and, in turn, transform those ideas into a more detailed roadmap.

Deliverables

The deliverables for the Specification Review depend upon how large the application is and the time spent on the review. On completion of the Spec Review, the client will receive the following:

Requirement analysis

• An architectural roadmap recommending technical solutions
• A breakdown of the required software application into its core components, likely to include the approximate number of main features (e.g. forms, reports, etc.)
• An integration plan
• A deployment strategy
• An MVP (Minimum Viable Product) will be identified, as well as a wish list - requiring the client to set the priorities for the project by defining what is in and out of scope for the MVP
• A detailed list of 'issues' associated with the existing system which impact future development and maintenance
• Hardware and licensed software recommendations
• Mock-ups if required

Product Backlog

• A list of Product Backlog Items (PBIs) will be broken down based on the requirements analysis and the architectural design
• These PBIs will then be estimated

Ballpark $ estimates

• The estimated number of Sprints
• The estimated number of developers
• The estimated cost of the project

From wireframes to the final product

During the Spec Review process, we create wireframes to give the client a preview of the functionality and look of their proposed solution.

These wireframes are utilized in key stages of the development process:

• The developers talk to the client to gain a deeper understanding of their needs
• The developers design the wireframes for the client to envisage and sign off
• These wireframes are the direct reference developers use to work from
• The developers send the product back to the client to test
• The developers showcase the final product with a Done Video

Let's take a look at a real-world example.

These wireframes were created during the Spec Review and provided insight into the functionality of the client's new search engine to both the client and the developer.

As you can see, the wireframes allow you to gain a 'glimpse into the future' and give the clearest possible depiction of the end product.

A client will often ask for a proposal or ballpark for the project. It is very difficult to give them the price for a large project without first conducting a Specification Review.

The Spec Review is a process that will demonstrate to the client whether you have the commercial sense to understand their business and have the technical and management capacity to complete the project.

It is paid work conducted after the initial meeting to determine the overall scope, feasibility, and ballpark costs of the project (i.e. $50k or $500k).

E.g. Mr. Northwind learns that the idea he presented at the initial meeting will cost approximately $80K and he has to determine if that is feasible to his business or if he will trim the functionality to better manage the cost.

Spec Review length

The Specification Review is conducted by two experienced developers at the client premises in close consultation with the client. The time allocated for a Spec Review is generally 1 - 5 days depending on initial expectations of the project. The rule of thumb is 1 - 2 days of Spec Review per estimated month of project time.

The purpose is to understand the whole project but, if the project is greater than six months, focus primarily on the first six months.

Talk about business requirements

• Conduct workshops: Conduct workshops with different groups of users (e.g. management, back office, customer service) to build the "Product Backlog" which the business wants. This ensures that all users get their say. Some "nice-to-haves" might actually be quite easy to implement. Product Backlog Items can then be prioritized and fleshed out.
• Review documentation: Reviewing any documentation the client may already have. Remember clients are mostly looking to software consultants to assist them in solving business problems.
• Keep technology discussions short: Unless they have a specific business purpose, detailed discussions about technology with the client are unlikely to be useful. For example, most clients won't be interested in a discussion about whether to use .NET or Angular at this stage.
• Identify an MVP: Most client can't afford everything they want, so make sure you're keeping track of the minimum we can do to deliver value.

Do something valuable

Most software consulting experts will be able to provide a small improvement to the current system 'on the fly' during the Spec Review. This may be something as simple as adding an index to a table and thereby increasing the performance of a web page.

Use 'Corridor Conversations'

Corridor Conversations are a great way to set the clients expectations so you don't suprise them with a big number at the end of the Spec Review.See Do you have Corridor Conversations?

Estimates expressed in round numbers (or exact numbers for fixed price)

Remember, no politician challenging for leadership ever calls a vote before he or she knows the numbers; you too will avoid presenting a solution at a meeting if you aren't convinced the client is already agreeable.

Through the course of the Spec Review, the client will be aware that each month for senior software consultants is generally tens of thousands of dollars. Squabbling over $500 here or there in the ballpark phase is a level of detail neither side can be confident of. Clients need to be realistic about what they get for their money.

Read When do you use approximate values for project costs?

Technology options

At this stage, you want to consider the most relevant technologies. For example, SSW will likely pursue recent Microsoft technologies. Some clients might want to do their own research or need some time to think about their options before agreeing to newer technologies.

Proposal

You should follow Rules to Better Proposals when documenting a Specification Review.

Test Please

The consultant must run a Test Please by another developer and your Account Manager before anything is formally presented to the client.

The main things the Account Manager will be looking for will be:

• Have you already had corridor conversations with the client so they're already expecting the ballpark estimate?
• Are the estimates realistic and still incorporating any relevant buffers? e.g. Project Management, bug fixing, etc.

Example Schedule for a 1-day Specification Review

You want to have all the required work for a Spec Review done within the allocated time, so it’s important you leave time to implement the required changes after you present and before you email the final version.

• 9 am: Meet with the client and discuss requirements
• 11 am: Start work on the backlog and the PowerPoint (.PPTX) or Word Doc (.DOCX)
• 3 pm: Present to the client and gather feedback for changes
• 5 pm: Implement changes
• 6 pm: Send “As per our conversation” with Word or PowerPoint attachment

In a 2 or 3-day Spec Review, you should assume you’ll need more time to implement changes, so move the presentation time earlier to 2 pm.

Timesheets

Always track timesheets against a separate Spec Review project.

It makes project cost reporting difficult later if you don't, since the cost we're looking for is always the "post-Spec Review cost" that clients can compare to the estimate you gave in your Spec Review.

The hallway is your friend. It's a place where you can gather a lot of information informally.

Formal meetings can have a "Us vs Them" feel - While the information collected and the conclusions of the Spec Review are presented formally at the end of the Review, it is important that the consultants convey key points to the client as they emerge through the course of the Review. The formal presentation is not the time to be presenting new information to the client.

Addressing key potential sticking points of budget and technology informally during the course of the Spec Review relieves the potential for unwelcome surprises during the Spec Review presentation. Canvassing the issues beforehand in casual 'corridor conversations' clears the decks for an agreement, rather than increasing the risk of heated discussions if you surprise a client at a formal meeting.

Some other topics that should have corridor conversations are:

• Estimated Cost and Time
• Key Technologies
• Key Infrastructure

For example, ask the client "...building the cube will add around 2 months of development time, shall we leave this out of the current scope, or do you want it in?"

Ensure that any discoveries or decisions are properly documented.

The most important part of being in a Spec Review is adding value to the conversations. How do you make sure that your presence is adding value to the discussion and the product?

Here are some tips:

Tip #1: Know when to speak up

Knowing when to speak up can be one of the most difficult tasks for some people. Often when talking in a group, finding a spot to add in a point is difficult. When you have a question or something of value to add, try using the phrase, "Before we move on..." or use the Teams hand 👋 feature. If you don't speak up, important information might be missed or features may be left unrefined.

Tip #2: Think of other developers

Sometimes you might not have all the expertise to architect a clients' solution. If you need outside expertise, remember that you can ask quick questions to other developers. You can let the client know that this isn't your specialty and that you'll ask a specialist and get back to them shortly.

Tip #3: Don't be afraid to double check a requirement

Make sure you understand what they want, do not be afraid to repeat and double check a requirement. It's better for you to understand it now then to go back and ask them again later.

Tip #4: Recommend ready-made solutions

Talk about already made solutions. There are often already made solutions to these very same problems. Be sure to Google beforehand. Present the Pros and Cons of these against a bespoke solution. Sometimes the ready-made solution solves their problem without any further work required.

Tip #5: Refine the problematic requirements

Talk about the most problematic parts. These are the areas that should have the most details, so make sure everybody is fully aligned about what is required.

Tip #6: Ask great questions

Questions are the key in understanding client needs. Asking a few simple questions goes a long way. Some examples are:

• What is the goal of the product?
• Where will the product be hosted?
• Are there any performance requirements?
• Are there any any reliability requirements? E.g. Has to respond in x seconds
• What are the security requirements?

Even the most seasoned analysts might occasionally overlook certain details in a Specification Review. Leveraging technology, especially AI, not only augments our capabilities but also acts as a safety net for those unintentional oversights.

The Role of AI in Enhancing Reviews

• Tool, Not Replacement: AI greatly aids in generating Specification Reviews. Yet, the expertise and discernment of a human are irreplaceable. AI provides a foundational understanding, but professionals provide the nuanced depth.

• Interactive AI: Foster a dynamic interaction with AI. Instead of providing it with a predetermined set of requirements, let the AI ask progressive questions. This way, it captures the intricacies of the project scope.

  Prompt: _You are an IT Consultancy specification writer.

  Engage with me step-by-step to gather essential requirements. Ask sequentially, with each question stemming from the previous response._

  Figure: Good example - AI adapts and evolves its questions based on ongoing answers, offering more tailored results

  Prompt: _Use these requirements to draft a Specification Review:

  1. Web application on Azure
  2. Capture user feedback
  3. User sign-up process ..._

  Figure: Bad example - Missing critical elements like security considerations, data migration paths, or integration with existing systems

• Customization Over Templates: While templates offer consistency, they may not always cater to project-specific nuances. Every project is unique, and relying solely on templates can lead to gaps in the specification.

Value Additions from AI

• Generating PBIs: Harness AI to create Product Backlog Items (PBIs) with both speed and consistency.

• Architecture Visualization: With tools like Mermaid, AI can manifest complex data into clear, interactive architecture diagrams.

  graph TB
  CUI[Cloud User Interface]
  CPM[Cloud Product Management]
  COM[Cloud Order Management]
  CAM[Cloud Admin Module]
  CPG[Payment Gateway]
  CI[Cloud Infrastructure]
  CUI -->|Order Placement| COM
  COM -->|Payment Processing| CPG
  CAM -->|Product Management| CPM
  CAM -->|System Configurations| CSC[Cloud System Configurations]
  CI -->|Supports| CUI
  CI -->|Supports| CPM
  CI -->|Supports| COM
  CI -->|Supports| CAM

  

• From Architecture to Specification: Entrust your AI with an architecture blueprint. See it draft an initial Specification Review, ready for human refinement.

  

Example

In harnessing AI, it's pivotal to recognize its value as a tool. Its true strength emerges when combined with our expertise, elevating the final output to unmatched quality.

Usually, a specification process is done with the client before beginning work on a project, just like you would never build a house without getting an architect to create a plan.

As you might appreciate, it is not realistic to understand the complexity of your system and give you a realistic estimate after a brief meeting. Our experience tells us we will need to spend a few days to obtain and document the requirements from your project’s stakeholders. This will help you turn your ideas into a more detailed roadmap.

The deliverables for the Specification Review depend upon how large the application is and the time we have spent on the review. You should have the following:

Requirements Analysis

• An architectural roadmap recommending technical solutions
• A breakdown of the required software application into its core components, likely to include the approximate number of main features (e.g. forms, reports, etc.)
• An integration plan
• A deployment strategy
• An MVP (minimum viable product) will be identified, as well as a wish list - requiring the client to set the priorities for the project through defining what is in and out of scope for the MVP
• A detailed list of 'issues' associated with the existing system which impact future development and maintenance
• Hardware and licensed software recommendations
• Mock-ups (if required)

Summary Product Backlog

• A list of Product Backlog Items (PBIs) broken down based on the Requirements Analysis and the Architectural Design
• These PBIs will then be estimated

Ballpark Estimates

• The estimated number of Sprints
• Estimated cost of the project

With the Specification Review, the client can see whether the consultant understands their business and the requirements for their software development project.

The ballpark estimate allows them to decide whether the project is feasible for their budget and time-frame.

Estimates contain 2 main classes of work:

• Relating to the particular product (e.g. create page 'customers.aspx')
• Relating to the project as a whole (e.g. management, administration, testing, software audit etc.).

PBIs may only make up about 60% of the total project time. Project Managers and developers should not think that the only work being charged on a project are coding tasks.

General Project Costs

Management costs can change depending on how much management the client requires. You should recommend a suitable level of management. 'Management, accountability and transparency' has a cost.

You should add general project costs as a % of the work items generally in line with the following (note that these numbers are just best guesses):

• Testing: 20%
• Bug Fixes: 20%
• Software Audit (if relevant): 4 hours per Release - usually conducted by two experienced Architects
• Fixes from the Software Audit: 5%
• DevOps: 10%
• Project Management: 15% - this includes items like stand up meetings, timesheets, standard updates, reviews, etc.
• Unknowns (for risky projects): 10%. While this is arbitrary it raises awareness for everybody that there are things we still don't know!

Project Specific Costs

Estimates for a project should be done by a developer, checked by another developer, and finally triple checked by an Account Manager. While every project is different in some way, there are common elements.

If the client requires a fixed price quotation, a 20% premium is added to the estimates for the Sprints specified in the Specification Release only (i.e. a fixed price is not given on the entire project). Requests for variations to a fixed price contract must wait until the contract is completed. If development is based on a fixed price contract, work is completed offsite only to facilitate project management and prevent unauthorized scope development.

How to create an estimate for a Spec Review (Summary)

This process can take up to a few days, so if you're just after a ballpark, use epics instead of PBIs (Product Backlog Items).

Here are the 8 steps:

1. List all of the PBIs into a Backlog in Azure DevOps (or visualstudio.com), sizing them with story points
2. Open Excel and connect to the above Backlog
3. In Excel, add a column called "Hours"
   Note: Once we move to estimating in time, this is no longer Scrum
4. In Excel, copy this list and paste into another spreadsheet called "Estimates Calculator" (see below for how to use this), in order to add all of the extra items (Testing, DevOps, Project management, etc.)
   Note: It would be great if Azure DevOps had functionality to “Add Standard Items" to a Sprint
5. Run a Test Please on the numbers
6. Add a screenshot of this spreadsheet to your Specification Review document under Costing Summary
7. Present to the client
8. When the estimate is approved by the client, start work following Rules to Better Scrum using Azure DevOps (Work Items).

Extra - How to use "Estimates Calculator"

Open the Estimates Calculator and do the following:

Why Microsoft Project isn't recommended

Microsoft Project is sophisticated waterfall planning software that has powerful features for auto-scheduling and dependency allocation (Note: Project allows you to add 2 people to a task, and then the calculations and dependencies are all worked out). However:

• In MS Project, tasks are auto scheduled based on dependency and resource allocation (who is assigned to it). This generates an estimated completion date which is never accurate, due to annual leave, public holidays and general shuffling of people in the team
• It gets the summing wrong (the totals don't seem to update and no way to trigger it)
• It's hard to synchronize with timesheets (as it doesn't connect to 3rd party timesheet systems out of the box – however, it does have its own time sheeting system... that is missing billing information!)

The findings of the Spec Review should be presented by the developers and the Account Manager at a meeting with the key decision makers of the project for review and acceptance. It is important that all the required people are in a room together to review the plan. It is also valuable to record this meeting.

If you've run the Spec Review successfully the client should not be surprised by anything you present. This means discussions should focus on issues such as what particular requirements could be added into the scope for the MVP, or what releases can be completed by what date, rather than spending the meeting helping the client regain consciousness after they blacked out from seeing the price.

The Spec Review presentation should be scheduled by the Consultant or Account Manager for the afternoon of the final day of the Spec Review.

• You are striking while the iron is hot
• All parties benefit while the information is fresh in their minds
• The client won't experience the inevitable delays when you go back to the office and get stuck on other client issues that appear more urgent

What does the client get at the conclusion of the Spec Review?

• Option A - Email (if they want to minimize documentation time)
• Option B - Word document (if they need to get approval from someone higher up)
• Option C - PowerPoint presentation (if they are the decision maker, and they don't want a doc)

• Option D - Video of PowerPoint presentation with narrations exported to a video (the best option to gather more feedback, you can even gather public feedback E.g. PointBank https://sswconsulting.github.io/PointBank/)

Video Examples

Once again, the presentation needs to pass a 'Test Please' from another senior employee before the meeting takes place.

Different clients will have different levels of documentation on what they want to be built. You need to be ready to do a Spec Review for any one of the following possible cases:

There are 5 levels/types of Specifications:

1. I have an idea...

Run from this
or
Verify they have a really hefty bank account!

2. High-Level Requirements Document

This will read like a wish list with no details and many unanswered questions. High-Level requirements are very vague and open to many interpretations.

3. Detailed Requirements Document

The details have been fleshed out and allow developers to write Functional and Technical Specifications.

• We need a login page for northwind.com
• Must match existing site look and feel
• Username is already in the Users table in the ABC database (SQL Server)
• Password should be at least 8 characters
• .NET is already used for the existing site so that is what this should use of course

4. Functional Specification

This will include detailed mock-ups for the UI, use cases/user stories and might be at a level to allow for fixed price quoting on the project. Functional Specifications go into more detail about the user interface and interactions in the system.

• We need a login page for northwind.com
• Must match existing site look and feel
• Users table must be defined and added to the ABC database (SQL Server 2008)

• Username consists of user first initial and first 7 characters of the last name

  • For example Joe Jones -> jjones
• Password should be at least 8 characters
• Site uses .NET 4 and this interface must be added to existing project
• This is the layout for the login interface
• A red asterisk (*) should be displayed if a value is left blank and Submit is pressed

5. Technical Specification

This is the blueprint for the application. There should be no unanswered questions and should allow for a fixed-price quote.

• We need a login page for northwind.com
• Must match existing site look and feel
• Users table must be defined and added to the ABC database (SQL Server 2008)

• Username consists of user first initial and first 7 characters of the last name

  • For example Joe Jones -> jjones
• Password should be at least 8 characters
• Site uses .NET 4 and this interface must be added to existing project
• Define the data model explicitly
  
• Must work with IE7, IE8, IE9, and FF3
• Must display correctly at 1024x768 resolution
• Must support ANSI characters for Username and Password
• Will not support mobile browsers
• Will not be tested with localization (assumes en-us local on US versions of software)
• SQL Membership provider will be leveraged

Product Backlog Items (PBIs) can be described in the form of a "User Stories" when appropriate. It ensures the developers will know the context for a PBI.

Figure: User Story - template for description

Specification Reviews can be a long process and not having access to the relevant parties that hold the vision and the budget can create obstacles.

Critical stakeholders are people with a sound understanding of the business requirements and control over the budget. These stakeholders are rarely technical.

When organizing the Spec Review, clearly communicate the importance of stakeholder attendance. There's no point in conducting a Spec Review without the critical stakeholders who ensure that business requirements are accurately recorded.

Make sure the stakeholders are aware of what is needed ahead of time. If all relevant stakeholders aren't available, be sure to warn that this will cause issues down the line. Remember, if no one in the Spec Review holds both the budget and vision, the product that you write up will look a lot different from what the business needs.

Getting accurate information from a client during a Spec Review ensures that the full scope of the project is captured and there are no surprises later on. Accurately refining the product avoids waste.

Here are some tips that should help focus in on a feature.

Tip #1: Check if the Product Owner can explain and show their process

Look at how they perform the task manually and listen to them explain the process.

Tip #2: Draw a Mock-up or process flow diagram as you listen to the requirements

Creating mockups or diagrams of the feature will be highly beneficial as the client can see the feature visually.

Tip #3: Consider a Prototype

Consider building a functional prototype (works, but throw away code).

Tip #4: Record Specification Reviews

Recording the Specification Review is another great way to make the information as clear as possible. Being able to look back and clearly lookup what was mentioned, saves re-asking questions.

Tip #5: Consider a Journey Map

Journey Maps help to highlight which person is responsible for decisions at various stages.

E.g. On this Journey Map observe the experience for the Producer and the Loan Officer. See how they move through the steps of obtaining and maintaining a farm loan.

The map highlights the emotional journey as described by these customers, including their points of pain and delight. In addition, you’ll find the technologies, systems, and touchpoint types used through the process.
From USDA Direct Farm Loans Journey

See the high-res version PDF.

Tip #6: Does the client know why you need to understand?

“I am not a code monkey. I solve business problems with code. I need to understand that problem to do that well.”

From Bryan Finster

A client will often ask for more features than are really necessary for the MVP. They may also think that implementing a feature is easier than it is.

There are a few things you can do to control the scope of the project and deliver the client the most value.

Tip #1: Flag problematic tasks as soon as possible

If a feature is going to take a long time or isn't going to deliver much business value, make sure to flag it to the client and make sure it really is a priority. Explain that you can always deliver the feature at a later date after they go live. By following these steps, only the features in the initial project are developed, saving the client time and money.

Tip #2: Estimate as you go

When you are doing a Spec Review, make sure you estimate tasks as you go. That way you can flag problematic tasks as soon as possible. Once you estimate a task, get another developer to check it incase you missed anything.

Tip #3: Flesh out requirements

If an estimate looks high, the requirements might not be fully fleshed out. Double check if the requirements are clear enough, otherwise follow-up with the client to discuss further.

When a Spec Review concludes, the journey towards project kickoff is only partially complete. For instance, imagine a scenario where the client had multiple questions and slight hesitations about the estimates provided during the Spec Review. Without a structured follow-up, these hesitations could evolve into concerns, possibly stalling the project before it even begins.

At the end of the Spec Review presentation with the client, work out a good time for the follow-up meeting and book it into their calendar immediately.

Objectives of the follow-up meeting

The follow-up meeting is a crucial step in ensuring a smooth transition from the Spec Review to the initiation of the project. Here's why and how we conduct this meeting:

1. Reaffirming priorities

Revisit the MVP backlog to ensure there has been no shift in priorities. It's essential to keep the project aligned with the client's expectations and business objectives.

2. Encouraging new insights

The Spec Review often sparks new ideas or considerations. Encourage the client to share any fresh insights or concerns, which could be pivotal for the project.

3. Clarifying estimates and timelines

Present an updated estimate reflecting any changes post Spec Review, ensuring clarity on the number of Sprints, developers needed, and the overall cost.

4. Outlining next steps

Clearly outline the subsequent steps, identifying any immediate actions required from either party to move forward.

5. Improving through feedback

Retro - Solicit feedback on the Spec Review process to continuously refine it, enhancing the experience for future projects.

6. Addressing legal and administrative details

Delve into any T&Cs, NDAs, or other administrative details requiring attention before project commencement.

Appointment template

To facilitate the scheduling of the follow-up meeting, here's a template that Account Managers can use:

Figure: Follow up appointment after a Spec Review

At the end of the Spec Review encourage the project to go ahead with the current resources, while it is fresh in their heads.

Say words to the effect of:

"The resources allocated to your project depend on availability. All efforts will be made to allocate the original resources used on the Spec Review, but that cannot be guaranteed.
If you decide today or tomorrow, then we can use the same resources...
Regardless, it is always better to move ahead while the project is fresh in the developers' heads."

Spec Reviews are a vital part of architecting a new solution for a client, they are the plans upon which a new project is modeled. They serve as a key stage in the pre-sales process for software development consultancies as they create an opportunity for the developers to demonstrate expertise and provide immediate value to the client. For these reasons alone, it is evident that those who are assigned to carry out this exercise must be well-trained in the matter.

Importance of Specification Reviews

As the documentation delivered at the end of the Spec Review is the foundation upon which the project is built, it is imperative that the proposed solution meets the client's needs as closely as possible, this includes proposing the correct choice of technologies (factoring in their budget from corridor conversations) and providing realistic estimates of time required per resource.

Involving developers with no experience in Spec Reviews can lead to significant issues; underestimates, a misunderstanding of the right tech for the job, or a miscommunication between the developer and the client could all have huge implications on the success of the project down the line. This highlights the need for a structured training approach.

Learning Through Shadowing

Shadowing two experienced developers during a Spec Review is the most effective training method, providing real-world experience that allows the trainee to get stuck in and learn the process hands-on.

A developer who is shadowing should incur no cost to the client, this should allow the trainee to feel less pressured to perform, creating a healthy environment for them to learn. This also means the client to gains value, as they are getting an additional skilled resource at no additional cost.

Required Shadowing and Assistance

Before being able to partake in an unsupervised Spec Review, the trainee developer must complete 2 phases of training:

1. Shadowing Phase: Developers must shadow at least 1 Spec Review, observing and understanding the review's different aspects - they will act as a 'third' resource, assisting the other developers at no additional cost to the client.
2. Assistance Phase: Developers must then assist in at least 1 Spec Review as a 'secondary' developer, applying their observations and understanding their role in the process - they will be a billable resource, but will follow the lead of another experienced developer.

After successfully completing the shadowing and assistance phases, developers are ready to conduct Spec Reviews independently, equipped with the necessary knowledge and experience.

A User Journey Map (aka Customer Journey) is a visual aid that allows the clear communication of user needs.

Video: What is User Journey Mapping? (7 min)

These artifacts should be used at the beginning of a project during the early stages of research and design. This allows user requirements to properly inform design decisions made during development, and can help teams build a strong common understanding of a project. Capturing feedback in a Journey Map during or even after development, can provide high value as well. Pain points discovered in this way can reveal opportunities or areas for immediate improvement.

What is a User Journey Map

Source: nngroup

User Journey Maps are used to understand how a customer interacts with your product or services. There are many ways of presenting this information. Take a look at Smaply's example Journey Maps.

The key things captured in a User Journey Map are what steps/stages the customer goes through and also some indication of user sentiment at the time. Often the user journey will be mapped out and then research done to gauge user sentiment at each point in the journey.

This can be done using wireframes or mockups rather than going through the entire build of the software. This way any potential pain-points for users can be identified and improved before going through the costly exercise of developing software.

They are also used in follow up research to identify problems in existing software and systems. This is especially true in sales processes, where it is very easy to identify where user drop off occurs.

Service Blueprints

Sometimes the coding starts too early and, on some projects, the Product Owner needs more help to visualize what's being proposed. A great way to get in sync is to use Service Blueprints.

Source: nngroup

A Service Blueprint is a more detailed and process oriented document. This covers the steps from the User Journey Map and clearly details where and how the user journey will interact with the system being built. It also captures the various processes required inside the software. Often it will allow almost all API interactions to be captured, making it much easier for the developers to understand exactly what the various parts of the system are intended to do and what the user might be doing when they are called.

When to use them

Both these types of diagrams provide excellent documentation that is easily digestible, even by non technical people. They are especially valuable to verify with the Product Owner and to help the team understand the product vision. Because the Product Owner can easily understand what is happening, they can provide much better feedback than if they were simply provided UI wireframes or traditional documentation.

The team should produce these artifacts, typically not the Product Owner - this ensures what was in the Product Owner's head has made it to the team.

User journey mapping tools

• FigJam
• Miro
• A whiteboard and a stack of sticky notes.

Often when building systems it isn't super clear what all the nuts and bolts should be. The complexity of projects can vary quite a lot - and getting customers to tell us what they need is not easy. There might be several major stakeholders or domain experts each with slightly different ideas understanding that causes contention in how the system functions. Being a good consultant requires good listening and then good analytical skills to determine the customer's technical needs.

Event Storming is a fun collaborative modeling technique invented by Alberto Brandolini that enables members from different teams and disciplines to participate in workshops to learn how to break down complex business domains and processes.

Video: Do you know the value of Event Storming? with William Liebenberg (6 min)

The benefits of Event Storming

Having the client just talking to our consultants for a couple of days can be intense and it's difficult to stay engaged (on both sides), this is where Event Storming shines. Event Storming is fun and helps us to break down the complex requirements with hands-on client participation. We also get an awesome deliverable that we can use to develop a backlog and "better" estimates.

Another benefit of Event Storming is helping you determine the correct System Architecture. For instance choosing between a Monolith or Microservice architecture by looking at the groupings of domain events, commands and policies (aka Bounded Contexts if you are talking in pure Domain Driven Design DDD terms).

Event Storming can be done at different levels

There are multiple levels that Event Storming workshops can be run at. Each level continues to refine and enrich the domains with new concepts until a full end-to-end flow of the system is visualized. This end-to-end flow is valuable to the business itself but also helps accelerate software design and development.

Big Picture (aka 30,000 foot view)

• Explore the whole business across multiple boundaries by gathering people who each own/understands one part of the truth
• All Domain events are described in past tense (past tense because it's an event that happened, its a fact that cannot be changed)
• Capture hotspots or points of contention in a domain (this is usually when the experts don't all agree on a concept)
• Map the relationships between the domain and external dependencies

Example events:

🟧 InvoiceCreated

🟧 InvoiceReceived

🟧 EmailSent

🟧 ReportUpdated

Process Modeling (aka 10,000 foot view)

• Model a single business process from beginning to end and ensure no ambiguity or contention exists by clarifying all the business rules
• Enforce a timeline so that you can move events into the right order, and eventually see a process or flow emerging.
• Attach the actors, their motivations, and any dependencies required for executing actions (aka Commands)
• Enable stakeholders, domain experts and developers to communicate via ubiquitous language (all participants are able to communicate using the same terminology)

Software Design

• Now we have an end-to-end model of the system
• All relevant concepts are captured and documented
• The software design phase can proceed using methods from Domain-Driven Design (DDD), Clean Architecture and CQRS. Each sticky note can potentially turn into a Product Backlog Item during the software development phase.

Notice as you traverse the levels from top to bottom that new concepts are introduced that help describe the domain or process which gets us closer to being able to build a concrete software solution.

How to start an Event Storming workshop

To start an Event Storming workshop, get all the stakeholders, domain experts and developers into a room or virtual call.

From here everyone starts to write out all the events they think are necessary on the sticky notes and put the sticky notes on the real or virtual wall.

Check out how to run an Event Storming workshop for detailed steps and more information on how to prepare and run an Event Storming workshop.

Key concepts in Event Storming

Different colored sticky notes should be used to denote different concepts:

Domain Events - Orange

Actors (aka Personas) - Light Yellow

Policies (aka Business Process) - Pink

Commands - Blue

Aggregate - Yellow

External System - Purple

Read Model - Green

You can use whatever colors you can find, as long as a legend is always visible to the team.

Event storming is fun! Running a successful workshop requires preparation and understanding of the Event Storming process.

Every workshop has an Event Storming Master (aka Facilitator or Moderator) to guide participants through the workshop.

What are the responsibilities of the Event Storming Master?

The person taking on the role of Event Storming Master does not need to be the project Scrum Master or Technical Lead - as long as they know and understand the Event Storming concepts and discovery steps then they can run the workshop.

Before a workshop

Before a workshop, the Event Storming Master is responsible for: preparing the Event Storming workshop session which will include:

• finding the right participants
• allowing the right amount of time
• finding the right space (physical or virtual)

During a workshop

During a workshop, the Event Storming Master is responsible for helping participants to:

• follow the Event Storming rules
• focus on the learning the modelling of the business domain
• ask the right questions when getting stuck
• timeboxing the discovery steps

Invite the right people

It is important to invite the right people to the workshop. Missing key participants or having too many participants

• Developers or Engineers usually ask the right questions
• Domain experts are the people who will answer the questions
• Dedicated Event Storming Master that will help guide the participants through the workshop

Schedule the right amount of time

Depending on the size and complexity of the project you would typically need between 2 to 4 hours for a good Event Storming workshop session.

During a Specification Review you can schedule this workshop on the first day. Typically on the second day you can use the Event Storming visuals to help design your system and software architecture and produce better estimates.

Preparation - In person workshop

• Different colored sticky notes
• Marker pens
• Long roll of paper or
• Wide white-board or
• Office glass walls or windows

It is important to make sure that the common terms are recorded and clearly visible during the workshop.

Finally, make sure that the legend (explaining all the key concepts of Event Storming) is clearly visible.

Preparation - Choosing the right visualization tool

Real-time collaboration (remote or in-person) has become the default choice for many teams. Instead of sticky notes and white-boards we can use tools such as:

• Miro
• Lucidcharts
• Diagrams.net.

These tools will eliminate the worry of low-quality sticky notes falling off the white-board and your markers drying up!

For remote sessions, collaboration might not be as smooth as the in person events. However, it is also easier to arrange the attendees to join a remote session when the team is not all in a single location.

Discovery Steps

You can break the workshop down into a number of distinct discovery steps. Each step adds more detail to the business domain or process you are trying to understand.

1. Domain events
2. Concerns and questions
3. Domain Commands and Personas
4. Read Models and Aggregates
5. External Systems
6. Policies

Step 1: Discovering Domain Events

Use the orange sticky notes for Domain Events.

The domain experts and stakeholders can simply start recording the events that occur in a business domain or process. The events don't necessarily need to be in a precise timeline order (yet).

Domain events are always rooted in the past tense to represent a fact. Facts cannot be changed because they actually happened.

For example, we can have domain events such as Invoice Created Email sent Timesheet Updated.

It can be expected that not all the participants will be aligned with the business domain or process at the start, but as the workshop progresses everyone will start to "get into the zone" and ideas will be put onto the board quickly and smoothly.

When there are concerns or contention, the participants can discuss and rearrange the events until it is resolved and everyone is aligned in their thinking. Sometimes the contention is due to a different terminology, so it is important to record the common terms and make sure that they are clearly visible to all participants.

The Event Storming Master should check the stickies to ensure that the basic rules are being followed (such as ensuring events are in the past tense), but instead of just correcting the stickies directly, they can be marked or rotated to be corrected at the end of the step. The Event Storming Master should not interrupt the participants while they are putting events on the board.

Step 2: Discovering Concerns and Questions

Use the red sticky notes on corresponding domain events when a concern or question is raised.

This will make it clear to participants that not everyone is aligned and will prompt further discussions until everyone is aligned.

Step 3: Discover Domain Commands

Use the blue sticky notes for Commands (also known as Actions).

Use the light yellow sticky notes for Users / Actors / Personas.

Commands are the result of a User making a decisions and executing an operation.

In this step we dive into the Mechanics and Core components of the domain. The discussions about commands and actions will prompt us to ask questions such as "Why does user X need to perform a particular command?"

Once the events ordered chronologically we can start seeing a flow emerge.

Step 4: Discover Read Model and Aggregates

Use green sticky notes for the Read Model data sources / projections.

Read Model shows the data that a User needs data to make a decision.

At this point you should be able to start building up the Aggregates (entities).

Step 5: Discover External Systems

Use purple sticky notes for External Systems or Dependencies.

External Systems represents parts of the business domain or process outside of our control such as:

• API Services
• Departments
• Other organizations

We expect external systems to respond to our Commands and/or Queries.

Step 6: Discover Policies

Pink for Policies (aka Reactions)

Policies are the glue between the Commands and Events.

Policies are considered the reactive logic that represents the rules of a business domain or process. This reactive logic allows or denies the target event to be triggered.

Always spoken in terms of 'When-X Then-Y' or 'Whenever'.

For example:

• When a user logs > 8 hours work, then send a warning email and add to overtime
• Whenever an invoice is updated with < 8 hours, then send a warning email

End Result

Lots of sticky notes arranged chronologically that shows:

• Commands & Events grouped with Aggregates
• Defined Read Models with data that Users need to make decisions
• Identified External Systems / Dependencies
• Identified Policies (reactive logic) that apply to the process

If you ran an in-person workshop using sticky notes and a white-board you should capture the end-to-end flow by taking a photograph or by digitizing it with one of the diagraming tool listed in Preparation - Choosing the right visualization tool.

Make sure that he flow is stored in a central repository where everyone can access it.

Having access to this visual flow:

• can help new team members onboard
• clear up confusion when parts of the system is not understood
• accelerate the software design and development of the system or new features

At your company, you never want to have a person asking "Where is that file?"The answer should be "The answer is Teams, the question is irrelevant".

Microsoft Teams is a great solution for organizing client files and conversations. Create a new Team for each of your clients, and if you have multiple projects for one client, use Channels to keep them separate. There's no need to create a new Team just for a new project.

Once you have this set up, it is likely that you want to have a link between your Teams instances and the associated CRM record.

In the video, Adam Cogan describes how they connect Dynamics 365 and Teams with an extra field. They change the Account table to add a custom column 'Teams-URL'.

Level 1: Manual method

To get that URL, simply click the ellipsis next to your Team name and click "Get link to Team".

Level 2: Automatic (Basic)

Add a button to the Ribbon to provision a new team and link to it.

How to add the button to the Dynamics Ribbon?

• Customize the command bar - Power Apps | Microsoft Docs (new approach - customizing command bar using the command designers)

or

• Ribbon Workbench (old approach - using the ribbon workbench)

Level 3: Automatic (Advanced - best UX)

Using a PCF control you can add a button directly into the form that can do everything for you.

Click on this section on your CRM Dynamics to have a Team created:

Note #1: Alternatively, this process can even be automated using Azure functions and Graph API to provision a new Team every time a new client is created in CRM. This has the disadvantage that every single Account would get a Team...and that could create a real mess of unused Teams.

Note #2: The Team's name can get out of sync if the Dynamics client name is changed, therefore you need one extra flow that is called when the client name is changed to keep them in sync.

See how the PCF can make UI's shine.