Entries:
Comments:
Posts:

Loading User Information from Channel 9

Something went wrong getting user information from Channel 9

Latest Achievement:

Loading User Information from MSDN

Something went wrong getting user information from MSDN

Visual Studio Achievements

Latest Achievement:

Loading Visual Studio Achievements

Something went wrong getting the Visual Studio Achievements

Jump into UML Sequence Diagramming with KangaModeling

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...

KangaModeling

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 
participant Alice
Alice->Bob : Hi!
activate Bob
Bob-->Alice : Hey!
deactivate Bob


produces this diagram:
image
See KangaModeling Documentation for full language tutorial.

Key Features

  • 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).

Additional Features:

  • 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

Tiny UML Sequence Diagram Markup Language for Agile Developer Documentation

What is a GOOD documentation?
That’s why it’s important having a good documentation. A good documentation must:

  1. … cover only aspects which can not be easily derived from code, interface or intellisense. Duplication is waste.
  2. … 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!
  3. … be about problem solving, not restating the facts.

As an example there are over 20 Stream classes in .NET with at least 3 levels of inheritance depth. Let’s say a component I’m going to use requires a Stream as 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 MemoryMappedViewStream derived from 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 Studio and 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

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?

http://kangamodeling.org/

Currently there are three ways to use KangaModeling:

  1. Use the public web API

    The public web API is available at http://kangamodeling.org/api.

    Set up

    A JavaScript client for the web API can be retrieved from http://kangamodeling.org/api/js. Just reference this to get the entire functionality on your site.

    <script type="text/javascript" src="http://kangamodeling.org/api/js" />

    The JS client uses jQuery, so you additionally need to reference it, for example from the jQuery CDN.

    <script type="text/javascript" src="http://code.jquery.com/jquery-1.7.2.min.js" />

    Functionality

    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:

    <pre class="kanga" data-kanga-type="sequence" data-kanga-style="sketchy">

    title Hello World

    Alice->Bob: Hi!

    activate Bob

    Bob-->Alice: Hey!

    deactivate Bob

    </pre>

    Which when converted by the JS client will be replaced by the appropriate visual representation:

        title Hello World 
    Alice->Bob: Hi!
    activate Bob
    Bob-->Alice: Hey!
    deactivate Bob
    image
  2. 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.

  3. 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.

image

SNAGHTML134f10a8

SNAGHTML134f63f5

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...

Tags:

Follow the Discussion

  • Rikard NordbergRikard Nordberg

    see
    http://www.websequencediagrams.com/

  • @Rikard Nordberg:

    agree - websequencediagrams - is great, but :

    • There is no source code available
    • Really interesting features are not available in a free version
    • You can not install and host it yourself let's say inside corporate intranet

    Kanga is 100% free - open source (pure c#) and can be installed on any IIS.

Remove this comment

Remove this thread

close

Comments Closed

Comments have been closed since this content was published more than 30 days ago, but if you'd like to continue the conversation, please create a new thread in our Forums,
or Contact Us and let us know.