A simpler way to make flowcharts in Notion and Github
September 26, 2022
Sooner or later in development work, there comes a time where you just need a flowchart.
Recently at Basedash we were designing a UI pattern for managing items using a modal. We wanted a slightly different behavior depending on whether you’re adding a new item, or editing an existing item. Here’s what the modal looks like (for defining a User Input for an Action):
We started out with a desire to do up-front validation, where if a user provides invalid values for a given item (e.g. leaves a required field empty), then we would not permit the item to be saved, we would keep the modal open and prompt the user to fix the issue or discard the item.
This up-front validation approach adds complexity, so much so that I felt a need to make a flowchart to use for development. I was hesitant to reach for a drawing/design application, or for dedicated flowchart software. I prefer to keep my tooling fairly minimal. That’s why, after searching around a bit, I was happy to come across Mermaid. I love the ability to just worry about the structure and leave the drawing part to be automatically generated.
Mermaid to the rescue
Mermaid is tool which will generate a nice flowchart for you from plain text. You use Mermaid’s syntax to define the nodes and connections in the flowchart, and Mermaid renders a nice vector image for you. And what’s more, it is supported by Notion, and by GitHub, so you can share your flowcharts with your collaborators in such places.
In any area that supports Markdown, for example, a PR description, add a Mermaid diagram by putting it inside a triple-backtick-delimeted code block with the “mermaid” designation, like so:
And then toggle between “Write” and “Preview” to see the rendered flowchart, like so:
In Notion, type forward-slash then “code”, and you should see a prompt to create a code block. There’s an additional code block option for a Mermaid block, like so:
Then you can edit your Mermaid code and see the flowchart there below, like so:
There’s also a dropdown to change between “Split” (shows both the code and the generated chart together), and “Code” (shows just the code), and “Preview” (shows just the generated chart).
Our modal pattern, developed with the help of flowcharts
Here’s the flowcharts (and the code that generates them) for the aforementioned modal logic, done in Mermaid:
Example flowchart: Add-item modal with up-front validation
Example flowchart: Update-item modal with up-front validation
How we use such flowcharts for development
Having such a flowchart as a reference has proven helpful for clarifying and enumerating the possible conditions and the expected behavior for each. They’re not necessarily intended for implementation purposes, for that we take the codebase as the source of truth, but here’s where they have proven valuable:
- A human-aid for documenting and comprehending the expected behavior in the abstract
- Sometimes it’s helpful to just look at the sequence, without getting distracted by the concrete visuals of a real UI.
- A guide for manual testing
- E.g. after making a change to the implementation, prior to putting up a pull-request, I would take the UI through each branch of the flowchart and verify it behaves as expected.
More to the story: wherein we decided to simplify things
After coming away with a viable implementation of the above flowcharted behavior, after reflecting on it, and further discussion, we decided that this up-front validation was more trouble than it was worth, both from a user experience standpoint, and from a code maintenance standpoint. We also landed on a different philosophy for this kind of UI flow: let the user provide invalid input, don’t block them right away. Let them even perhaps save invalid input, and then, when the time is appropriate, give a warning, and when the time comes that the user attempts to execute what they’re working on, given the invalid input, only then will they have the need to remedy the issue. Like letting a developer save a code file even though it may have a syntax error.
So, after doing away with up-front validation, here’s how much simpler things stand now:
Example flowchart: Add-item modal (what we went with)
Example flowchart: Edit-item modal (what we went with)
Isn’t that simplification just lovely? Makes me think, if we weren’t barking up the wrong tree in the first place, pursuing “up-front validation”, we wouldn’t have had such a complex UI development task, and I wouldn’t have ended up wanting to make a flowchart, and possibly, I wouldn’t have discovered Mermaid at all.