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 ony 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)


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.