Motivation
As a software architect, I spend quite a bit of my time in design discussions. That’s an integral part of the job, for a good reason. As I see it, the design conversation is a fundamental part of this job and its role in the organization.
Design discussions are hard, for various reasons. Sometimes the subject matter is complicated. Sometimes there’s a lot of uncertainty. Sometimes tradeoffs are hard to negotiate. These are all just examples, and it is all part of the job. More often than not, it’s the interesting part.
But another reason these discussions tend to be hard is because of misunderstandings, vagueness and lack of precision in how we express ourselves. Expressing your thoughts in a way that translates well into other people’s minds is not easy. This gets worse as the number of people involved increases, especially when using a language where most, if not all, people do not speak natively.
From what I observed, this is true both for face to face meetings (often conducted remotely these days), as well as in written communication. I try to be as precise as I can, but jumping from one discussion to another, under time pressure, I also often commit the sin of “winging it” when making an argument in some Slack thread or some design document comment.
I’ve argued in the past that diagrams serve a much better job of explaining designs. I think this is true, and I often try to make extensive use of diagrams. But good diagrams also take time to create. Tools that use the “diagram as code” approach, e.g. PlantUML (but there are a bunch of others, see kroki), are in my experience a good way to create and share ideas. If you know the syntax, you can be fairly fast in “drawing” your design idea.
Still, I haven’t found a tool that will allow me to conveniently express what I need to express in a design discussion. Simply creating a simple diagram is not all of the story. I often want to share an idea of the structure of the system – the cooperating components, but also of its behavior. It’s important to not just show the structure of the system, and interfaces between components, but also highlight specific flows in different scenarios.
There are of course diagram types for that as well, e.g. sequence or activity diagrams. And there are a plethora of tools for creating those as well. But the “designer experience” is lacking. It’s hard to move from one type of view to another, maintaining consistency. This is why whiteboard discussions are easier in that sense – we sit together, draw something on the board, and then point at it, waving our hands over the picture that everyone is looking at. Even if something is not precise in itself, we can compensate by pointing at specific points, emphasizing one point or another.
Emulating this interaction is not easy at this day and age of remote work. When a lot of the discussions are done remotely, and often asynchronously (for good reasons), there’s a greater need to be precise. And this is not easy to do at the “speed of thought”.
Building software tools is sort of a hobby for me, so I set out to try and address this.
Goals
What I’m missing is a tool that will allow me to:
- Quickly express my thoughts on the structure and behavior of a (sub)system – the involved components and interactions.
- Share this picture and relevant behavior easily with other people, allowing them to reason about it. Allowing us to conveniently discuss the ideas presented, and easily make corrections or suggest alternatives.
So essentially I’m looking to create a tool that allows me to describe a system easily (structure + behavior). A tool that efficiently creates relevant diagram and allows me to visualize the behavior on this diagram.
Constraints and Boundary Conditions
Setting out to implement this kind of tool, as a proof of concept, I outlined for myself several constraints or boundary conditions I would like to maintain, both from a “product” point of view as well as from an engineering implementation point of view.
- The description should be text based, so we can easily share system description as well as version them using existing versioning tools, namely git.
- The tool should be easy to ramp up to.
- Just load and start writing
- Easy syntax, hopefully intuitive.
- Designs should be easily shareable – a simple link that can be sent, and embedded in other places.
- There should not be any special requirements for software to use the tool.
- A simple modern browser should be enough.
Scenaria
Scenaria is a language – a simple DSL, with an accompanying web tool. The tool includes a simple online editor, and a visualization area. You enter the description of the system in the editor, hit “Apply”, and the system is displayed in the visualization pane.
The diagram itself is heavily inspired by technical architecture modeling. The textual DSL is inspired by PlantUML. You can play with the tool here, and see a more detailed explanation of the model and syntax here.
Discussion doesn’t stop with purely static diagram. The tool also allows you to describe and visualize interactions between the different components. You can describe several flows, which you can then “play”, on the drawn diagram. You can step through a scenario or simply play from start to finish.
After this is done, you have a shareable link, as part of the application which you can send to colleagues (or keep).
As a diagramming tool, it’s pretty lacking. But remember that the purpose here is not to necessarily create beautiful diagrams (though that’s always a plus). It’s mainly about enabling a conversation, efficiently. So there’s a balance here between being expressive in the language, while not going down the route of adding a ton of visualization features which will distract from the main purpose of describing a system or a feature.
Scenaria is more intended to be a communication tool to be used easily in the discussion we have with our colleagues. It can serve as a basis for further analysis, as it provides a way to structure the description of a system – its structure and behavior. But the focus isn’t on rigorous formal description that can derive working code. It’s not intended for code generation. It’s about having something to point at when discussing design, but easily create and share it, based on some system model.
An Example
An example scenario can be viewed here. This example shows the main components of the Scenaria app, with a simple flow showing the interaction between them when the code is parsed and shown on screen.
Looking at the code of the description, we start by enumerating the different actors cooperating in the process:
user 'Designer' as u;
agent 'App Page' as p;
agent 'Main App' as app;
agent 'Editor' as e;
agent 'Parser' as prsr;
agent 'Diagram Drawing' as dd;
agent 'ELK Lib' as elk;
agent 'Diagram Painting' as dp;
agent 'Diagram Controller' as dc;Each component is described as an agent here, with the user (a “Designer”) as a separate actor.
We then define an annotation highlighting external libraries:
@External {
color : 'lightgreen';
};
And annotate two agents to mark them as external libraries:
elk is @External;
e is @External;Note that up to this point we haven’t defined any interactions or channels between the components.
Now we can turn to describe a flow – specifically what happens when the user writes some Scenaria code and hits the “Apply” button:
'Model Drawing' {
u -('enter code')-> e
u -('apply')->p
p -('reset')-> app
p -('get code')-> e
p --('code')--< e
p-('parseAndPresent')-> app
app -('parse')-> prsr
app --('model')--< prsr
app -('layoutModel') -> dd
dd -('layout') -> elk
dd --('graph obj')--< elk
app --('graph obj')--< dd
app -('draw graph')-> dd
dd -('draw actors, channels, edges')->dp
app --('painter (dp)')--< dd
app -('get svg elements')->dp
app --('svg elements')--<dp
app -('create and set svg elements')->dc
p --('model')--< app
};We give scenario a name – “Model Drawing”, and describe the different calls between the cooperating actors. Indentation is not required, just added here for readability.
The interaction between the agents implicitly define channels between the components. So when the diagram is drawn, it is drawn with relevant channels:
At this point the application allows you to run or step through the given scenario where you will see the different messages and return values, as described in the text.
Next Steps
This is far from a complete tool, and I hope to continue working on it, as I try to embed it into my daily work and see what works and what doesn’t.
At this point, it’s basically a proof of concept, a sort of an early prototype.
Some directions and features I have in mind that I believe can help in promoting the goals I outlined above:
- Better diagramming: better layout, supporting component hierarchies.
- Diagram features: comments on the diagram (as part of steps?), titles, notes
- Scenario playback – allow for branches, parallel step execution, self calls.
- Versioning of diagrams – show an evolution of a system, milestones for development, etc.
- Integration with other tools:
- Wikis/markdown (a “design notebook”?)
- Slack and other discussion tools
- Tools and links to other modeling tools, showing different views of the same model.
- A view only mode – allow sharing only the diagram and allow playback of scenarios.
- Allow embedding of the SVG only into other tools, e.g. a widget in google docs.
- Better application UX (admittedly, I’m not much of a user interface designer).
- Team collaboration features beyond version control.
Contributions, feedback and discussions are of course always welcome.