There's a Kanga in my Model... Using KangaModel to easily and painlessly create,share and display sequence diagrams
George Mamaladze - 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:
- … 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.
...
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’ve 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?
...
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. As an example following code
...
We are gone even one step further. Our open source project KangaModeling at kangamodeling.codeplex.com 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.
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.
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).
..."
"..
kangamodelling.org is a web service which generates and returns a diagram image based on code snippet you posted to the URL using POST or GET.
Usage
You can use it in your Blog,Wiki or Website to generate nice looking diagrams from compact markup.
Placing the code
Place your markup code on the page and surround it with <pre> tag. Set class attribute to kanga.sd.
...
This project came across my desk yesterday (Thanks George!) and the more I look at it the more I think it's pretty neat. There's a number of cool things here. The dev in me digs that the source for all this is available and cries out to me to check out how the parsing and diagramming is done. The manager in me likes the idea of how simple this is to get started with and how quickly sequence diagrams can be created all without expensive tools. The doc guy in my head likes that the images are dynamic and easy to keep up to date and how easy they are to share on a web site.
If you've thought Sequence diagrams hard or too much of pain to keep up for your project, you should check out KangaModeling...
Posts
No comments:
Post a Comment