Actions and pictures both speak a thousand words. Being able to draw a picture to represent your ideas for action before executing them is an important part of effective planning, but how can we make this process easy?
Before going to the drawing board directly, you may still want to write down your drawing contents of your idea that’s needed for your diagram. If that’s the case, why not use the same text contents to produce your final diagram using text-based diagramming mechanism? Such mechanism is nothing but diagram as code.
In MuleSoft, API Led and Microservice architecture due to its nature where an application network is built using loosely coupled services, this is even more significant to visualise complex interactions in a better way with ease yet produce quickly, modifiable, and reusable diagrams without manually drawing but using a source code convention to convey your API architecture design using a Design Driven Development approach for developing and managing API integration effectively.
There are many modern GUI based tools that help you drawing your designs to visualise ideas. These can be desktop applications or online web tools like diagrams.net, Miro, Microsoft Visio or even Microsoft Word or PowerPoint etc for drawing visual diagrams.
However, if you have been working as Solution Architect or Designer or Senior Developer who is producing such diagrams, you would notice a diagram cannot be easily updated.
It consumes lot of time even for minor text or shape or color or layout changes in redrawing and styling or to that matter you cannot expect review or suggestions from your target audience without great efforts or without screensharing demanding your presence and explaining while pointing your mouse on drawing components such as arrows, boxes, shapes etc.
Additionally, (re)drawing complex diagrams can waste your project time while your changes to your ideas are rapid, whereas a textual content can be easily written and updated line by line.
It is a catch-22 situation where having to write to represent your action or idea is complicated and drawing and updating the static diagram is also complicated with the above reasons!
Now imagine the above picture is in markdown like textual format and the picture frame (as application) can display an updated picture. Instantly the moment you change the formatted text and, at the same time, allowing any of your team able to change or able to review even independently to the original author, making the diagram instantly and up-to-date without opening the original diagram authoring application! Making changes to existing diagram can be adding more elements or removing elements or changes to content or adding styles etc.
This gives a new dimension your audience who can provide feedback/review on visuals element by element, or on diagram text whilst everyone is still able to view the updated diagram instantly whilst you are making text changes truly reflecting the speed of your ideation!
So, in practice, you have made a diagram as code and delivered product as per that design, but it may not be the end of the project, as you may have more changes or feedback from customers or target audience and you want to go back to drawing room and review with your team and need to make further changes to additional diagrams. This is made easy with this approach using text-based diagramming.
Finally, you want to have your requirements, use cases, architecture designs & project plans, process flows etc as diagrams but easily modifiable sos you will not have diagrams out of sync with your constantly changing plans during the entire project life cycle from idea to production and beyond with all diagrams always up to date.
Then you are headed towards a right direction. The solution is to use markdown like language which is to mark your plain text using a formatting notation that will produce a diagram easily, where you can easily update text content as and when diagrams need modification with different versions. This promotes more reviews to your idea or diagram eventually helping your teams to refer the latest agreed idea and take actions just as per agreed scope and as seen in the up-to-date diagram.
Therefore, your architecture and design for your software implementation version can be maintained for each version as documentation (user guide, technical specifications, user manual etc) without involving huge efforts by redrawing the whole diagram(s) again. A markdown source code can be maintained part of your project code repository.
This makes your diagrams as part of the source code rather than sitting somewhere which gets outdated quickly due to constant changes in ideas and source code! Eventually, you will realise a diagram cannot be created/updated/maintained as fast as your ideas change unless you are able to express your ideas into plain text, but with some markdown style syntax in it which can be rendered as easily as a diagram!
There are many more benefits with this approach.
Note: These diagramming tools are not modelling tools which means these tools will only help you to create or update diagrams as per your ideas but not necessarily prevent you creating incorrect models by software modelling definitions. Also, there are limitations if you are having too many actors, participants, the final diagram will really look complicated for understanding and so rather you can make more simple sub diagrams of a big picture to communicate your intention or make alternate visualisations to represent your end goal.
DIAGRAMMING TOOLS & OFFERINGS
What is Markdown language? How do you write Markdown language? How it supports modifiable diagrams? What tools are there to use? Is it integrated with any existing tools?
The Markdown language is created by John Gruber in 2004 (not a latest invention) to create visual diagrams while making them appealing to humans using plain text as source code using simple formatting notation.
Markdown is a lightweight language and is simpler that its formatting notation, can be written in plain text using even with notepad editor. It is used to create a diagrams using markdown description language. The simple syntax you use takes you to creating pictures without drawing a picture by yourself with the help of certain markdown applications that understands and parses or renders the markdown content for you as final diagram.
You can even create many different contents using markdown like websites, notes, documents, eBooks, presentations, email, team collaboration and technical guides etc.
The idea is to read and understand the formatted text by human even if it is not rendered by target application. Hence your markdown (md) content is platform independent.
There are many applications support markdown and even cloud based online tools available. E.g. Dillinger, that immediately convert your markdown into HTML and displays in web browser in real time. Hence you do not need to install or download any app or software.
Markdown language is supported by many diagramming tools/editors to satisfy different domains, areas and needs. Below tools are just a few of them, out of many more, are available under different purposes with commercial, free software and opensource licensing.
There are even commercial editors that allow your team to collaborate online effectively allowing to edit markdown content by team members even using role-based access control. There are many more such complex use cases and tools that support markdown for different needs. Each tool may have been serving different diagramming or other purposes mentioned above.
These markdown language and tools are integrated with popular applications so you will not be left out to use and benefit for your project needs.
For a proper text-based or visual modelling tool, you can use C4 model for zooming into detail diagram from high level model. For text-based diagramming modelling you can use C4-PlantUML, For visual modelling, there are even tools like Archi (Open Source), Sparx Enterprise Architect (proprietary) etc for creating different views from your abstract model.
How can I write plain text (.md extension) file to draw my MuleSoft API-Led design as UML diagram? What diagrams can I draw? What tool, can I use?
For instance, in MuleSoft integration area, you will have the following some of typical design elements that you may be considering while drawing design diagrams using some of the above diagramming tools.
MuleSoft API Design elements
Watch this space for more details on how to use some of these diagramming tools to represent architecture diagrams, flow charts, pie charts, user journey, sequence diagrams, project plans etc.
If you would like to find out more about text-based diagramming, give us a call or email us at salesforce@coforge.com