DEV Community: Joe Wallace

Standard visual modelling languages

Joe Wallace — Fri, 18 Nov 2022 17:35:08 +0000

Within the profession of Business Analysis, a key function is for the Analyst to be able to communicate ideas effectively, in a way that an intended audience is easily able to understand.

One way of doing this is visually modelling a process or system; a large benefit of this is to be able to distil complex concepts down into one easy-to-digest visual. Additionally, it’s easy to iterate on a model based on feedback, and new requirements coming to light.

In order to help Business Analysts, various standardised modelling languages have been created. In this article, we’ll focus on two of the most common ones: Unified Modelling Language (UML) and Business Process Modelling Notation (BPMN). When should you use them, and what do they consist of?

Unified Modelling Language 🌐

UML is an object-oriented modelling language, intended for use in a broad range of different domains, architectures and coding languages. It is focussed on the design of IT systems specifically, and as such can be used for software or architectural designs.

What is UML good for?

Interactions within an IT system or between IT systems.

Determining objects used by a system, and the data items within them.

Communicating architectural designs to stakeholders with technical expertise.

Automated generation of code and/or test cases.

There are two different types of UML diagrams:

Structure diagrams

These demonstrate the objects and components within an IT system and how they relate to each other. Various types of structure diagrams are available, including:

Class diagrams
Denote object classes within the system, and the relationships between them.

Object diagrams
Similar to class diagrams, but show how the user of a system might see the objects within it.

Composite structure diagrams
Also similar to class diagrams, but also show the composite parts within classes.

Component diagrams
Depict how system components hang together and depend on each other.

Deployment diagrams
Denote the distribution order and configuration required when deploying an IT system.

Package diagrams
Model how packages in the system fit into the overall application model and their dependencies.

Profile diagrams
Allow you to document prototype data structures using “stereotypes” - domain-specific data models which can be used for more formal class or object diagrams later.

Example

Example class diagram on Diagrams.net

Behaviour diagrams

These demonstrate dynamic changes which may occur within an IT system as a result of user or automated triggers. Many different behaviour diagrams exist, including:

Use case diagrams
Describe how users and systems functionally interact with an IT system, in a series of steps.

Activity diagrams
Graphical representations of the workflow through a system, organised into swim lanes.

Interaction overview diagrams
Similar to activity diagrams, but with a focus on interactions over workflow.

Sequence diagrams
Models dependencies in the flow of an IT system in sequence.

Communication diagrams
Similar to sequence diagrams, but more focussed on how processes interact than on the time sequence.

Timing diagrams
Also similar to sequence diagrams, but with an emphasis on the amount of time each process takes.

State diagrams
Show which state transitions are permitted and how they are triggered.

Example

Example use case diagram on Diagrams.net

Business Process Modelling Notation 🔁

BPMN is a process-oriented modelling language, intended to represent the full business process supporting an IT system. It is based on flow charts, and likely to cover areas outside of the scope of a software or architectural change being investigated or proposed.

What is BPMN good for?

Mapping out business processes underpinned by an IT system.

Determining the different scenarios that may occur, and how a system should behave in each scenario.

Communicating system behaviour to all business stakeholders, regardless of technical knowledge.

BPMN has four main components:

Flow objects
These can be events (triggers for the beginning or end of a flow), activities (processes or sub-processes undertaken by a user or system within the flow), or gateways (decision points where the flow can branch off in multiple directions).
Connecting objects
These can be flows of activities or messages (denoted by a solid or dashed arrow, respectively) or associations (links between an artefact and a flow object).
Swimlanes
These can exist on two levels: Pools (groupings of roles such as a function or organisation) and, within them, lanes (individual roles within the process).
Artefacts
These can be data objects (information required for a process), groups (which link together activities in a process), or annotations (textual descriptions of to give additional context).

Example

Example business process flow diagram on Diagrams.net

Epics: Purpose, structure, and content

Joe Wallace — Mon, 07 Nov 2022 16:36:29 +0000

✅ Epic User Stories, often called “Epics”, are simply User Stories which are too large to fit into an individual development timebox (“Sprint”, in the Scrum methodology).

❌ Epic User Stories are not themes which group together individual User Stories, new product features such a modules, or buckets of time to collect recorded time against.

The purpose of an Epic 🎞

The purpose of an Epic is similar to a typical User Story - an informal description of a user’s requirement, written in natural language relevant to the business domain. However, an Epic is less constrained by development capacity or process, so may describe a requirement a little broader and looser than required in a typical User Story.

The structure and content of an Epic 🧬

Epic User Stories, much like any other User Story, typically begin with a card describing the user’s problem, such as the “Connextra” template:

As a user persona
I want capability
So that business benefit

They will also have acceptance criteria like a typical User Story, to inform the test cases that are run to verify that the conditions to fulfil the user story have been met, as in the “Gherkin” template:

Given pre-condition
When user action
Then outcome

User Story mapping 📌

A process known as User Story mapping is often used by software development teams to sketch out a user’s journey through the system, break that down into Epics, and then break the (must have) Epics within it down into User Stories (of any priority).

See an example below for a holiday story map. Note that this might differ based on the scenario at hand and the needs of the customer. For example, if the customer had experience operating a boat, they might rent their own, and then a captain is not a must have!

Example story map on Diagrams.net

User Stories 101

Joe Wallace — Tue, 27 Sep 2022 10:27:24 +0000

What is a User Story? 📖

A “user story” in software development is an informal description of a user’s requirement, written in natural language relevant to the business domain, preferably without reference to the software in use (although sometimes this may be necessary), and worked on by a software development team.

It should also ideally be written by (or at least in collaboration with) a user, though they are also often typically written by a Business Analyst or Product Owner, and really can be written by anyone, if they have the right information on the business context.

User stories are conversation starters and anchor what a solution needs to facilitate, but they don’t define it. You may even be able to achieve what you wanted to in your user story without software development!

User Story Formats 🃏

User stories are often produced in a formatted fashion, largely to drive consistency or to help people to structure their thoughts, but they don’t have to be.

Typically at Advanced (and in many other software companies), user stories follow the “Connextra” template:

As a user persona
I want capability
So that business benefit

The lightweight nature of this format makes it useful in different contexts; on a project management tool like Jira, or physically, on a post-it note or index card.

The key part of any user story is the business benefit (or the “So that” on the Connextra template); if you can’t define why a user wants a capability in your software or process, you probably don’t need it at all!

User Story Splitting 🕷

User stories should be as small and self-contained as possible in their scope. This is both to ensure a focussed solution and to plan work in manageable chunks.

There are multiple methods of splitting user stories, but the most commonly used is SPIDR:

Spikes
Investigations and prototyping to better understand the ideal solution for a user story.
Paths
Different routes a user may take through a process, e.g. reschedule an appointment, or cancel it without rescheduling.
Interfaces
Different devices, browsers, or alternate interfaces for different types of users of the system.
Data
Different categories of information being managed or browsed, e.g. displaying someone’s allergies, or displaying their medication.
Rules
Constraints on the system, e.g. rules on the maximum number of appointments someone can have booked at once, or a minimum gap between appointments.

Acceptance Criteria ✅

Acceptance criteria are often added to user stories to determine conditions which need to be fulfilled when implementing the story such as to make it acceptable to the customer. These are used to inform the test cases that are run to verify that the conditions to fulfil the user story have been met.

These may take the format of simple bullet points, or use the “Given, When, Then” template (also known as Gherkin):

Given pre-condition
When user action
Then outcome

Example User Story 🔍

As a District Nurse
I want to be able to view a patient’s allergies when visiting them in their home
So that I don’t prepare them food or medication that may be dangerous to them

Acceptance Criteria
Given a patient has any currently active allergies in their clinical record
When I open the patient’s visit on my tablet or phone
Then I will see them listed, with the causative agent, reaction severity and description shown

Technical Debt and Technical Efficiency

Joe Wallace — Wed, 14 Sep 2022 14:12:56 +0000

Technical Debt: “The Loan” 💰

Within agile software development, one of our key aims is to get working software out as early as we can. This allows us to enable the value for our users quickly (and therefore bring in revenue as a business) and get early feedback to improve and iterate the product in line with customer needs, without wasting time on things customers might not ultimately want.

While we may refactor our code as we go along, this tends to mean that though the software we deploy works as intended, it may not be as efficient as we’d like. These inefficiencies are often called technical debt.

Technical Efficiency: “The Repayment” 💳

It is important to address inefficiencies in our code over time, for a multitude of reasons: To reduce the likelihood of bugs occurring, to make the code base more manageable, and to improve performance, among other things.

Therefore, its recommended that each product at Advanced sets aside a bucket of time in each release period for technical efficiency - refactoring and improving code to “pay back” the technical debt, like a loan we took out in order to deliver the software early. When American developer Ward Cunningham coined the term “technical debt”, this was exactly what he meant - repaying technical debt is essential, much like paying back a loan.

Technical Product Initiatives and Technical Efficiency 👩‍💻

There are some scenarios where initiatives we want to complete at Advanced are technical in nature, for example:

Replacing a third party component or platform.
Upgrading to a new version of a framework or integration.
Changing our authentication methods.

These initiatives are often erroneously categorised as “technical efficiency”, as the end user does not notice a difference in their day-to-day work. This is problematic, however, as these types of initiatives are not related to technical efficiency by nature, and due to their complexity and business benefit, need to be prioritised against other initiatives.

All of these initiatives should be considered like any customer-facing one, and supported by an appropriate business case that clearly quantifies the value of the initiative, and justifies why it should be done. For example, we wouldn’t be replacing a third party component for an abstract reason; we might be doing this because it causes unacceptable performance issues which are affecting the abilities for users to do their work, or the component might be going out of support, putting our entire service at risk.

It is vital that these items are prioritised and analysed in the same way that customer-facing initiatives are, with just as much care put into the business case. Prioritisation is a wider topic, the scope of which extends far beyond this article, but the following should be considered for more technical initiatives, as well as user-facing ones:

The business risk incurred in not completing the initiative.
Potential cost saving.
Potential revenue add, in terms of additional module sales or selling into new markets.
Customer satisfaction (and therefore retention).

Paying off technical debt is important, and freeing up space in our development teams' capacity by categorising these initiatives correctly helps us to recognise this.