Introduction
What's Revision all about?
The idea behind Revision is simple.
We want to enable you to create shareable, easy-to-understand visual models of your architecture as easily as possible.
The problem
Creating good diagrams is hard
It's hard to describe complex relations such as system architectures!
There are so many details and different roles need different types of information.
The best tool we have for describing these types of systems is architectural diagrams. Architectural diagrams have been the bread and butter of software design and fundamental for communicating and collaborating around software for a long time.
But again, creating easy-to-understand architectural diagrams that cater to all different roles within a team is not an easy task!
It's easy to try and describe too much in one diagram
When starting your first impulse is probably to create one big diagram for everything! As we talk about in the context and abstractions section that is rarely a good idea.
Too much in one diagram
Too many details in one diagram create diagrams that are hard to understand for all stakeholders.
It's easy to overuse notations
Notation refers to when one gives meaning to different shapes and colors in a diagram. For example, red boxes mean external components, the dotted arrow means responses and so on.
The danger of a notation in diagrams
Notions in diagrams force the users to understand them and make it hard to create diagrams that are easy to understand for all stakeholders.
Further, it's important to find a common look and feel and to make sure the diagrams are easy to access and easy to share.
Information is lost when using "dumb" images
When using general drawing tools for describing your architecture a lot of information is lost.
Information about what components have relations to other components, which components contain other components etc can't be stored in images and is lost.
A tool that is just a drawing tool can store that kind of information about the actual model that you're trying to visualize.
General drawing tools + Insights = 😕
For a general drawing tool, a box and an arrow is just that, a simple box and an arrow.
Making it impossible to gain further insights.
How we're solving it
Revision offers a solution to these problems by combining several ideas.
Abstractions to zoom in and out
Revision is inspired by the ideas behind the C4 model.
At its core, the C4 model created by Simon Brown offers a set of abstractions and a simple notation that one can use to create diagrams with different levels of detail. The model then describes how one should be able to navigate up and down between the levels, similar to how one would zoom in and out on a Google map.
C4 model offers a solution to the problem of describing too much in one diagram by guiding us to have just enough information on each level of abstraction and then link to the underlying level for more information about that specific area of the architecture.
Abstractions are built-in to Revision
Revision has built-in features for linking a component or relation in one diagram to another.
Making it easy to navigate up and down between abstractions and giving each stakeholder just the information they need.
Avoiding notations, keeping it basic
The C4 models also talk about the value of avoiding using color coding, line styles, different shapes etcetera to create a notation in your diagrams. Similarly, Revision only has basic shapes without the possibility of adding colors, border styles and so on - forcing us to build simple to-consume diagrams.
Avoid notation, just use basic shapes
To avoid creating complex notations Revisions come with just the basic set of drawing shapes - components, arrows and areas.
A behind-the-scene model
All shapes in Revision are part of an underlying model, shapes are created once and reused in other diagrams.
Utilizing a model instead of just images gives us a few advantages.
Model + insights = ❤️
Easier maintenance. We can find out where a shape is being used, change it, remove it etc.
Insights. Find out all relations to other shapes. See what other shapes one shape contains.
Query the model for the information you need.
Feed the model from the outside. Using Revisions API it's possible to import data into the model.
Quick and easy drawing and sharing
Even though Revision has many features a general drawing tool doesn't have it's just as easy to draw a new diagram. Things work just as you expect them to.
Revisions also have several built-in features for sharing your diagrams - everything from inviting people into the application to sharing a just-read link.
Want to display your diagram in another tool? Sure, that is possible to, just export an on-the-fly generated SVG, import it into the tool and share it with your team and stakeholders.