Building a shared understanding of your application with Sketch.systems
--
Over the last couple of months I’ve been getting into statecharts. It started while playing around with porting Reciprocal.dev (RIP) to work on top of tldraw as that uses them and since then, I’ve experimented with Stately’s excellent Xstate-based editor and then I found Sketch.systems.
Sketch.systems takes statechart visualisation a step further and in a manner similar to how I’d hoped Reciprocal.dev would play out, it allows multi-disciplinary team members to build a shared understanding faster via the use of visualisation and interactivity. Sketch.systems does this by enhancing statecharts with prototypes— making it easier for non-technical members of the team to see the impact state changes have on an application.
This state-driven prototyping approach is really powerful thanks to the text-based, markdown-like state specification schema that Sketch.systems uses, making it easy for anyone to read and write the state changes in plain text in a manner similar to Mermaid. The prototype is constructed using a render callback which takes the state model and passes that to a ReactJS component so that as the state visualisation is interacted with the rendered prototype updates.
Tools like Sketch.systems have the potential to increase the value of meetings where non-technical and technical team members spend large amounts of time translating between customer, business and technical requirements & constraints as the ‘sketch’ acts as a form of interactive living document of the system and updates provide feedback with very little development effort.
How Sketch.systems can help non-technical team members
Based on my experiences working in large teams, the hardest task has always been finding a light-weight means for visualising system changes in a way that non-technical team members such as Product Owners (PO), Business Analysts (BA) and Designers can consume, so there’s a fast feedback loop on how the underlying logic is reflected in the application.
I had some success in building a mix of User Journey and Business Process Modelling Notation (BPMN) in Miro to create a screen by screen flow with the underlying business logic underneath it (this would then become the inspiration for Reciprocal.dev), but this had some flaws — namely that only a few people on the team felt confident enough to update it due to the drag-and-drop nature of a Miro board.
I think Sketch.systems’ use of a plain-text, markdown style syntax for describing the system’s state and it’s changes solves this problem by removing the complexities of a fiddly UI and allowing for that textual representation to be copy and pasted with ease across tools so POs & BAs can workshop through the various channels they engage with before bringing the final version to the rest of the team.
Designers on the team can use the statechart to build up a design system of UI components and their states easier as they can ask questions about missing states and how the UI would feedback back to the user that they have entered a specific state. The prototype during this stage can be an embedded image / iframe and as the development team implement the UI this can be swapped out for the appropriate HTML & CSS.
While non-technical team members can get very far building up an understanding with the state syntax, its visualisation and an image based prototype, the real value will come from collaborating with technical team members who will map the state changes to the lower level processes and feedback on updates to the statechart or provide additional supplementary information such as test data and test plans for each state.
How Sketch.systems can help technical team members
When translating how an application will meet a user’s needs from business-friendly language to a bunch of 1s and 0s it always helps to have as much supporting information as possible and a statechart is an excellent resource to have available, especially if it’s easy to collaborate on and read.
Within the development teams I’ve worked with the information has come from a disparate set of individuals:
- User Stories and Acceptance Criteria came from the Business Analysts
- Design System documentation came from a Design Agency based on separate discussions with the BA
- Architecture diagrams and external service documentation came from an Architect overseeing multiple teams
- Non-functional requirements would come from the BA or a Test Lead
This would often result in long meetings/calls where the development team and the aforementioned parties would try to translate all the requirements for a story into a series of tasks but if there was a single document that represented the system and that document could be explored then it’d be easier to build a shared understanding and this time could be reduced immensely.
To better understand the data needs of the application, the technical team can start creating a set of test data to pass to the props for each state as they build up the prototype which will make it easier to implement model-based testing and this test data can also help validate contracts with external services.
If the team has built up a component library in React they can start validating their compliance with the design system earlier on by using that library within the prototype, similar to how Storybook helps teams do this but with the added statechart resource for other team members to use when providing feedback.
There is a Storybook plugin to include a statechart via Xstate but due to the complexities in defining a statechart (even with Xstate’s excellent editor) I’d favour using Sketch.systems’ editor for making it easier for non-technical team members to participate in making changes, and while a Sketch.systems statechart doesn’t provide as much technical information as one created in the Xstate editor (you can document side-effects of state changes for example) you can export a Sketch.systems statechart as Xstate JSON to import into the Xstate editor. This will likely need to be done once the Sketch.systems version of the statechart is signed-off to avoid managing two versions of the same statechart.
For technical team members I think the biggest advantage using Sketch.systems gives them is the ability to communicate with different parties using different artifacts. It can be with a BA about state changes and updating the statechart or an external provider about an API contract using the test data model that they produced to power a prototype.
What I think could make it even more powerful
Here’s a few things that I think could provide even more value for teams using Sketch.systems:
- Version control — As a system evolves over multiple releases it’s likely that bugs are introduced, being able to roll-back a version of a system sketch will allow teams to explore a version that matches the one in production
- JS package import — The prototype code editor could be made even more useful if a team could import their component library to use in their prototypes
- Data modelling — In order to pass data into the prototype you need to define all your data in the code editor, it’d probably enable better discussions within the team if there was a non-code way to define this data (such as YAML or spreadsheet-like editor)
- Support for other JS frameworks — Not all teams use React and as the state model is passed in a prop it’d be cool to see different frameworks being supported so teams can re-use existing code
- Attaching links & more to state steps — It’d be nice to attach links to supporting documentation and other resources to a state step. This would really help team members build up an understanding of the system and would help with data modelling, traceability and other activities the team will be doing
- Export a map of prototypes for each state — To provide more context for non-technical people it would be helpful to see a flow-chart like map of the statechart but with each state represented by the prototype. That way the design consistency and wording can be verified as a whole
Summary
Sketch.systems is a really useful tool that will enable your team to have more productive conversations about the system you’re building. It’s text-based, markdown-like syntax lowers the complexity of defining the state of a system which makes for quicker feedback loops, allowing for misunderstandings to be cleared up before development starts.
I look forward to seeing how the tool develops and reading the success stories of the teams that use it.
