An App From Scratch: Part 3 – Workflows

8 minute reading time; ~1460 words

---

Hello there!

Today’s post is taking our requirements and starting to talk about workflows.

If you haven’t read the previous posts, I’d suggest you start at An App From Scratch: Part 1 – What To Build. You can also find all the related documents and code here: Building Tailgunner.

Workflows

In our last post, we refined our user stories with the use of wireframes. Taking that one step further, we’re going to take one of our user stories and pull out all the workflows that the story is trying to get done, either explicitly or implicitly. If we wrote our requirements well, we’ve already managed to cover a lot of what we need the tool to help us do, but now it’s time to find the gaps.

What Is A Workflow?

A workflow is a series of tasks or actions that achieve a specific goal or outcome, completed by a user interacting with a system (ex: using a tool) or a system interacting with a system (ex: an API call).

The workflow defines how a process flows logically, outlining steps, inputs, and outputs required to complete the desired activity efficiently.

For example, the workflow “Take out the trash” may be defined as:

• Empty trash cans and tie off bags.
• Take the bags to front door.
• Open the front door, and take the bags outside.
• Close the front door.
• Take bags to curb and stack them neatly.

Why Write Out Workflows?

Just like the previous documentation we’ve worked on, documenting workflows helps give us clarity around what to implement, hopefully giving us a better result in the end.

As a solo developer, this kind of planning is extremely detailed, and there is a balance to be struck in how time is spent on a project. For the purposes of this series, I’m going to document some workflows, but normally you’d only aim to do this with:

• complex interactions with specific needs (ex: regulatory).
• a team that involves multiple developers or stakeholders.
• a tool or app that is expected to be invested in over a long period of time.
• where the tool or process interacts with external APIs.

While documenting workflows can be extremely useful, not every project needs this level of detail. If you’re working on a rough prototype, a simple CRUD app, or a product with a very limited audience (or all three 😂), your time is likely better spent in other areas.

However, because we’re aiming to build a more robust tool (and to illustrate best practices in this series) we’re going to explore these workflows in depth.

Defining Our Workflows

We’re going to focus on US1 in this exploration, and identify the key workflows that the business owner can do:

As you can see, what appeared to be a simple story that we started with has in fact revealed a variety of workflows that the business owner will need for this story to be successful.

Breaking Down A Workflow

Now that we have a list, let’s take a workflow and give it some detail.

Writing out this workflow easily highlights that there are often a lot of assumptions baked into every story. For example, if I, as an engineer, received a story to build a tool for creating templates, I likely would have implemented or reached exactly this workflow. However, not every engineer approaches tasks the same way, and the outcome can vary depending on the developer’s experience, priorities, and interpretation of the story. If your requirements are highly specific, it’s always better to be explicit upfront, and save time and stress later on.

That said, when working with more senior engineers, you often don’t need to define requirements at this level of detail. Experienced engineers tend to have an intuitive sense of how an application should function (because we’ve built so many), and we’re more likely to iterate and refine the work as it progresses.

Explaining The Structure

This whole structure is about getting everyone aligned on how to complete the specific workflow. As you’re working through defining a workflow, you should try to avoid being either too vague or too detailed. This applies to both the actions taken, as well as the details included about user interface or experience, as the focus should be on what’s required to tell the story of how something gets done, not how it looks or feels (those things come in later stages).

Pre-Conditions

These are the things that we need to satisfy for this workflow to be started. These are generally non-negotiable, and they can usually be broken down into three groups: user, data, and system.

Steps

These are the steps (in sequence) that are part of this workflow. Each step should be an action that the user or the system takes, and should be detailed enough to guide while still leaving some flexibility around how it’s implemented. For more complex workflows, these may be accompanied by or replaced by a diagram to make them easier to follow.

Outcome

This details what should happen as a result of this workflow being completed. These results should be observable or measurable, and detail what effect the workflow had on the user or system.

These outcomes are important, and will guide how the workflow is implemented, help create testing plans, and can also tie back to project or business success metrics.

Validating Workflows

Now that we’ve defined a workflow, we get to the next part of the process: ensuring they hold up to real-world use. Validating workflows involves checking whether they address the requirements effectively, are aligned with what the user needs, and that we’ve covered any important edge cases or pitfalls.

There are a couple different ways we can validate a workflow:

• Review Against Requirements
  Compare the workflow to the user story and requirements, to see if we missed any key details.
• Simulate User Scenarios
  Walk through the workflow from the perspective of the end-user, looking for any gaps or inefficiencies. See if the workflow feels smooth and intuitive.
• Test For Edge Cases
  As you look at the workflow, look for things that might break it, like invalid data, missing permissions, or what happens with unexpected inputs.
• Get Feedback
  Talk with other developers, designers, end-users, or other people involved in the project to get a different perspective on how it works, and help reveal any blind spots.

Taking the time to validate the workflows that you’ve come up with helps to make sure that they are not just functional, but also user-friendly and practical. On top of that, it also helps mitigate the risk of rework later in the project, and ensures you deliver something that delights the end-user!

Wrapping It Up

Drilling into just a single story and workflow shows how much depth can be involved in planning and designing a project (and explains why some projects end up with thousands of pages of documentation 😁).

Up to this point, we’ve been looking at the project from a functional design lens. In the next part, we’re going to start looking at the more technical aspects of the planning work as well, bridging the gap between product development and technical implementation.

Did I miss something in my workflow? Share your thoughts in the comments below!

Thanks for taking the time to read this, and stay tuned for the next part: system design.

Cheers!