BLOG about IBM Rhapsody. Contains technical information as well as more private travel stories.

Tag: MBSE (Page 2 of 2)

Who needs documentation anyway?

Yes who?

Everybody of course. Don’t be daft. I know software developers hate writing documentation. Why do i know that? I am a software developer myself… takes one to know one.

But when using Model Driven Software development, documentation is not that hard anymore. In fact, you are writing documentation while you are developing, almost without noticing it.

Oh, don’t get me wrong here, it is not done fully automatically, you have to do the right things, like putting effort in the way you build up your model. When you don’t, the same happens when you write source code without documentation.

It is fully possible to create a working (meaning: the code you generate will do what is expected) UML model from Rhapsody without a chance to understand what is happening by reading the model. Or as we used to say: you can mess up things pretty bad but to really screw things up requires a computer…

So. Let’s assume we modelled the right way. Now what? The boss wants to see what we did and I have to present the model for him/her on paper. How do we do that?

Well: Rhapsody offers multiple ways to document your models and make the information available to others.

  1. Use Rhapsody. Sounds a bit awkward but the best way to look at Rhapsody models is with…. Rhapsody. Don’t start with: But that is too expensive… there is an Architect Version that suffices for viewing the model for about € 600,- But a tiny bit of knowledge about models is required so that might not be the 100% solution.
  2. Use Reporter. It’s free. And it does documentation! So where’s the drawback? Well… it does documentation but that’s about it. There’s no formatting, you can only decide on a high level what will be in and what not, it’s just in RTF, no other formats and you can edit the documents but they will be overwritten when you regenerate them. So…. only limited use.
  3. Reporter Plus, is the version that costs. I’m not sure what the price is but since you only need one, normally, that should not be a problem. This can write Word, PowerPoint, RTF and even HTML (with javaScript). The last format is pretty cool, it can build a web version of the model where you can click your way through as if you are using Rhapsody. The creating of the documentation template is a lot of work but not really complicated. Can document what and how you want.
  4. Publishing Engine is the successor to the Reporter Plus. Can document data from multiple tools, that can be quite handy when you also use Doors or other IBM Tools. Must also be purchased , but again, mostly only one license is needed. Is also not too complicated but a lot of work to make perfect documentation.
  5. Another method is often overlooked. But is sometimes the best way to do stuff. The Rhapsody Java API! It can access the model, it is built-in, (for free!) and is not too complicated. You are free to create any doc you like.

So. I hope this helps you in deciding how to document! If you have any questions, don’t hesitate to ask!

Happy Modeling with Rhapsody

Walter van der Heiden (wvdheiden@willert.de)

 

Stuttgart

I do a lot of traveling. A whole lot of traveling. Mostly Germany but sometimes outside or way outside. But the city I travel to most is Stuttgart. Not because my car was made there but because we have lots and lots of customers here.

Stuttgart and the surrounding cities are not bad, just the traffic is really murdering. They even beat Munich in traffic jams. Part of it is caused by the geography, Stuttgart is a hole between some hills, there is no way you can build decent roads, what is there must be used, no room for more roads.

The other cause is the so-called “Stuttgart 21” plan. This involves railway only but it will take the complete main station and move it underground. If you look where the station used to be it looks like a nuclear bomb just went of…. Big hole with lots of machines. This has its influences on railway traffic but also on everything that goes through the city.

This week is Rhapsody Training at a customer. 5 days! A long time ago a 5 day Rhapsody Training was normal, unfortunately this is no longer the case. It went to 3 days, often only 2 days and there are companions that estimate their employers to be able to learn UML and Rhapsody in 1 day.

This is, of course, total rubbish. Learning UML and Rhapsody takes just as long as learning ‘C’ and compiler/debugger. If by now you think: “Learning ‘C’ goes quick” then please dig your memory for the truth…,. Before you are an experienced ‘C’ programmer, years go by!

The UML is not more difficult or easy to learn, it is just different. And… you have to know ‘C’’ (or ‘C++’) before. This is what Rhapsody generates.

What is difficult about UML/Modeling? Well.. the way you do it is very different from traditional source code programming. I think that is the most difficult part for most “converted programmers”. Modeling is an art, you learn it by doing a real good training (like ours… 😉 ) and by doing it! You need to practice, read a lot, try a lot.

I see many people using Rhapsody The way they use their IDE, try until the code generator produces the desired output. This is wrong! Follow the paths that people like Bruce Powel Douglas and others have described in books, modeling is a lot of work. In the end you will save because the number of errors and changes will be way lower than with traditional programming.

It pays off to invest in a good process (which diagram should I use when?, what information is where?)  and in making your model so that it is actually your documentation. Modeling takes time but it is time you have to take anyway to give your brain the time to understand what you are doing.

I always say: a model behaves just like your car. If your car is dirty, it does not drive “good”. As soon as you wash and vacuum it, you will sense that it drives “better”. Subconsciously, admitted but true. A model behaves the same. If you make it nicer, with straight lines and with elements that have the same size and are outlined you will notice that it makes more fun to use the model. Some think that the drawing part is wasted time: trust me, it’s not!

So beautify your model, insert navigation information so that other can also find their way in your model, use enough diagrams, (every diagram should answer a question) use requirements that you connect to model elements to show traceability. Use stereotypes, profiles and tags to store information in your model. After a while you will do that automatically and the quality of your modeling will increase dramatically. Also re-use will be much easier than it was.

Happy modeling with Rhapsody

Walter van der Heiden (wvdheiden@willert.de)

Newer posts »

© 2026 Rhapsody TechBlog

Theme by Anders NorenUp ↑