This week we're going to do a theme week, focused loosely on diagrams. Today's project is one that I thought pretty neat and one I've used myself to help diagram and communicate a design. The beauty is in its simplicity.
You've heard of UML and Sequence diagrams? This project helps you create them, again simplify and easily. Yes, I said UML and simple...
What is KangaModeling?
KangaModeling allows you to produce UML (like) diagrams very easily.
The main idea is to generate the diagram from a lightweight markup textual diagram description language.
Following code:title Hello
Alice->Bob : Hi!
Bob-->Alice : Hey!
produces this diagram:
See KangaModeling Documentation for full language tutorial.
- No mouse kicking - KangaModeling is made for those who think that full-fledged modeling tools are overdesigned for visualizing communication and relations between software components.
- Always up to date - if you use a diagram in wiki or blog it is often additional overhead to open a modeling tool, update the diagram, export to image and upload it back.
- That's why we provide a web service which will produce diagram image from markup in your blog on the fly. You can use our web service at KangaModeling.org.
- Alternatively if you are looking for an intranet solution - you are welcome to download our ASP.NET web application and host it yourself (for free).
- KangaModeling.Compiler helps you to generate consistent diagram by producing error messages and hints.
- KangaModeling.GuiRunner is a demo application which can also be used to create diagrams.
- KangaModeling.WebRunner allows you to generate diagrams from markup direkt into your wiki or blog see also KangaModeling.org.
Here's a little more background on KangaModeling
What is a GOOD documentation?
That’s why it’s important having a good documentation. A good documentation must:
- … cover only aspects which can not be easily derived from code, interface or intellisense. Duplication is waste.
- … be easy to maintain. Wiki like public knowledge repositories or Q&A platforms like Stackoverflow are good examples. They are easy to edit – if you see and outdated or wrong post, go ahead and fix it!
- … be about problem solving, not restating the facts.
As an example there are over 20
Streamclasses in .NET with at least 3 levels of inheritance depth. Let’s say a component I’m going to use requires a
Streamas input. What I need is a kind of guidebook to help me finding the right one based on context of my application. All I want to know is that somewhere there is a class named
UnmanagedMemoryStream(which is derived from
Stream) that meets my requirements. But what I get as a first hit in MSDN search is a detailed method descrition of string. Basically the same thing I see when I press dot key in
Visual Studioand intellisense box comes up.
Diagrams – pro and contra
To get to the point – the central message of this post is that one diagram tells you more than 100 auto generated documentation pages.
For instance a class diagram showing inheritance hierarchy and relationships between classes could be a great help to get an overview about available functionality and make right choice. (See an example with Stream above). To win the same information from code you will probably need hours of jumping and navigating.
A sequence diagram is another brilliant sample. Due to many indirections, wrapping, tiny classes and methods (which are very good!) it is often not too easy to read a call stack. Sometimes you are looking at a huge call stack trying to understand what’s really going on. What you wish is a high level view on major players in some particular scenario and the way they interact, talk to each other. Having a sequence in such a moment is a great help.
Diagrams are also documentation. Well we’v discovered that they are necessary, because they cover aspects which can not be really easy read out of code. So point 1 from our 3 is satisfied. But what about maintainability?
- – - – - – - – - – - – - – - – - – - – - – - –
To create a diagram we usually use some modeling tool. I used Enterprise Architect for a long time but now I am a fan of Visual Studio modeling capabilities (unfortunatelly available only with Ultimate edition). So:
- You need a modeling tool to create a diagram.
- If a community should maintain the documentation (the Wiki approach), ALL of contributors must have the SAME modeling tool.
- If a contributor wants to update or adjust the diagram slightly he needs a SOURCE modeling project for that.
- You have an export / import publishing overhead with diagrams. You need to export a diagram you designed to some supported format and include it in documentation, typically by uploading an image. Well … and you have to do it every time you make an adjustment.
Maintainability overhead is probably the reason why open source projects having excellent wiki-s are using diagrams so rarely.
The solution is as simple as elegant. It comes initially from authors of www.websequencediagrams.com. The main idea is to generate the diagram from a lightweight markup textual diagram description language.
Okay, you like that idea, how can you start using it today?
Currently there are three ways to use KangaModeling:
Use the public web API
The public web API is available at http://kangamodeling.org/api.
The JS client uses jQuery, so you additionally need to reference it, for example from the jQuery CDN.
When you include the JS client it will automatically perform a diagram conversion as soon as the DOM is ready.
To let the automatic diagram conversion happen place your markup code on any HTML page that references the JS client and surround it with a <pre> tag. The JS client looks for all pre elements with its class attribute set to kanga. To tell the JS client what type of diagram it should produce, set the data-kanga-type attribute to the approriate diagram type (currently, the only valid value is sequence). To tell the JS client how it should render the diagram set the data-kanga-style attribute to the diagram style of your choice (currently, valid values are sketchy and classic).
Putting it all together your HTML has to look like this:
title Hello World
Which when converted by the JS client will be replaced by the appropriate visual representation:
Use the self-hosted Kanga Web API
The project KangaModeling.Web.Api compiles to an ASP.NET MVC3 application that can easily be published to the IIS of your choice. This is the best choice if you want a stable and secure API under your control.
All the guidelines mentioned above apply to the self-hosted Kanga Web API.
Use the Kanga Executables.
The projects KangaModeling.GuiRunner and KangaModeling.ConsoleRunner both compile to windows executables you can use on your local machine.
So you can use it via a public Web API or you can grab the source for the entire thing and host it yourself.
I grabbed the latest check-in, set the start-up project to the GuiRunner, it compiled and ran with no problems at all.
If you've been looking for a quick, simple and easy way to create sequence diagrams or wondered at how you'd create a like diagramming solution yourself, KangaModeling is calling your name...