Click here to Skip to main content
13,143,774 members (33,723 online)
Click here to Skip to main content
Add your own
alternative version


14 bookmarked
Posted 6 May 2012

Tiny UML Sequence Diagram Markup Language for Agile Developer Documentation

, 6 May 2012
Rate this:
Please Sign up or sign in to vote.
Tiny UML Sequence Diagram Markup Language for Agile Developer Documentation

I hate overdocumented software components and frameworks. There are top 3 reasons for that:

  1. Only the code tells the truth ( The good component expresses its intended way of usage through good structure, expressive naming. Ideally, it is designed the way that does not allow wrong usage.
  2. Any documentation tends to became outdated. Reading such a documentation can be misleading and frustrating.
  3. And finally, to be honest, who reads the documentation first? No one does. Usually, we come back to documentation after we get stuck. While reading it, we understand that all the facts that are described we’ve already discovered ourselves, but the point we are stumbling over is not covered at all.

What is a GOOD Documentation?

That’s why it’s important to have a good documentation. A good documentation must:

  1. … cover only aspects which cannot 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 an 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 find 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 description 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 the 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’ve discovered that they are necessary, because they cover aspects which cannot 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 (unfortunately 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 The main idea is to generate the diagram from a lightweight markup textual diagram description language. As an example, the following code:

title Hello 
participant Alice
Alice->Bob : Hi!
activate Bob
Bob-->Alice : Hey!
deactivate Bob

would generate this diagram:

We are gone even one step further. Our open source project KangaModeling at provides a web server application which generates diagrams on the fly. So you can include sequence diagrams in your Wiki articles, blog posts or web sites with just several lines of markup.

... you can include sequence diagrams in your Wiki articles, blog posts or web sites with just several lines of markup.

Placing the Code

Place your markup code on the page and surround it with <pre> tag. Set class attribute to

<pre class="">    
    title Hello World 
    Alice->Bob: Hi! 
    activate Bob 
    Bob-->Alice: Hey! 
    deactivate Bob

Making It Work

Finally, to get the whole thing to render properly on the page, you have to add JavaScript to the page.

<script type="text/javascript" 


For optimal results, place this code at the very end of your page. A sequence deiagram will appear in place of your markup code.

For internet posts, you can use our publicly available web service at
For intranet solutions, you are welcome to download ASP.NET web service code from Installing it on any IIS will prevent sensible information from leaving your intranet.

We are going to keep improving and providing additional features. As a next big step, we plan to provide you with language and service to also generate class diagrams.

Go on and try it out. Join us if you like KangaModeling. Help us by contributing or reporting issues and wishes.


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


About the Author

George Mamaladze
Software Developer
Germany Germany
Tweeter: @gmamaladze
Google+: gmamaladze

You may also be interested in...


Comments and Discussions

GeneralMy vote of 4 Pin
leacasas15-May-12 5:55
memberleacasas15-May-12 5:55 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Terms of Use | Mobile
Web04 | 2.8.170915.1 | Last Updated 6 May 2012
Article Copyright 2012 by George Mamaladze
Everything else Copyright © CodeProject, 1999-2017
Layout: fixed | fluid