(Modelling) Method documentation tool

Replies to This Discussion

Permalink Reply by Lothar Behrens on December 1, 2009 at 10:34

Interesting question.

I thought about similar issues of documenting my application in general. I am currently using Doxygen for the API and Open Office for the GUI application and how to use it in general.

In my view an ideal solution would be an application that is used to enter documentation artifacts for several elements that have to be documented. The application uses a database to store the articles and chapters and would be used to export the content as a XML file (may be docbook).

That way multiple developers could work on articles in parallel. XML gives you the freedom of choice what target format is used. Conflicts could be handled as alternatives.

When I think about documenting the modeling method, I would come to the initial documentation in the meta model. That documentation snippets per element could be extracted and added in the database.

Until now I only have the text, but no pictures like screen shots. Taking them manually may work once, but keeping them updated is my problem. But what if you create an assisting application for the method as a prototype?

Then it may be possible to activate recording screen shots while you using the tool. Then the screen shots automatically could be 'linked' to the meta model, as the modeler is generated from the meta model, thus, additional steps as taking screen shots would be possible (also doing that automatically if the model element the editor dialog is created of changes).

At the end I will have a database application where I could edit the documentation, having linked images to be used and also having initial documentation from the meta model.

Taking screen shots with an external app like AutoIt may also possible and the AutoIt script 'replays' the use case.

Lothar

• ▶ Reply

Permalink Reply by Geert Bellekens on December 1, 2009 at 12:13

I see where you are going.
My goal is indeed to have one repository of information and being able to extract the different formats for documentation I need.

So I know what I want, but now I need to know how.
Sure, I can create the metamodel, and write a bunch of tools such as document generators around it to extract the needed information in the required format, but I'm afraid my client won't be happy with the pricetag of such an effort.

Therefore I'm looking for existing solution to a problem that I feel every decently sized software development company has to face. Surely there must be a solution out there?!

Geert

• ▶ Reply

Permalink Reply by Geert Bellekens on December 1, 2009 at 12:20

Vlad,

I agree with you completely, the information about an element should be as close to this element as possible.
The problem is that the output (e.g. the model) is not sufficient for the different target audiences and the different uses.
Sometimes you just need a linear document that explains a number of subjects in a specific order.
People (including myself) sometimes need a printed copy of a certain aspect of the modelling method.

But the problem with things like word document, powerpoint slides,... is that they have a tendency to quickly become a maintenance nightmare.

I'm looking for a solution that will give me the output in the different formats I need while keeping the maintenance overhead minimal.

Geert

• ▶ Reply

Permalink Reply by Lothar Behrens on May 30, 2010 at 8:46

I have another idea to the output generating stuff.

Could it be easy enough to transform an UML model into a database representation?

Are there any tools that cope with that step?

Then any reporting tool based on databases could probably do the job for you. Say, one has a SQL report server running anywhere. Then one only needs to get the UML model into a database and some other staff could create matching reports (layout / format) and the report could be converted to Word, PDF or Excel by the reporting tool.

I am using an UML (XMI) to SQL Schema tool for my project as I am using a database schema as my model for my purposes. So I think this should be doable.

Lothar

• ▶ Reply

Permalink Reply by Xavier Seignard on May 31, 2010 at 15:22

I agree with you Vlad (sic)!
The documentation must be as close as possible of the metamodel.
So comments in the metamodel is a good way to do it.

With a past client, we also put hypertext links on the metamodel elements to get a more detailed information.

We also set up a blog, with various small screen casts on a single reference model, to explain tricky things. This single reference model was also the input of a fully automated building chain, so the end users could checkout the whole project and see what the M2T generation gave in a single (maven2) command.

And the cutting edge way to document a metamodel is to implement tons of live validation rules, so the modeler gets live feedback of what he's doing wrong. IMHO it's thousands time better than any documentation! But beware of fuzzy validation messages!

Regards,
Xavier

• ▶ Reply

Permalink Reply by Juha-Pekka Tolvanen on May 31, 2010 at 22:03

We have tried to automate the documentation part and make it always up-to-date. In practice this means that:
1) In metamodel all the elements have entries for documentation.
2) When modeling the entries form the language help (available in diagram, matrix and table editors from Help menu).

Since the documentation is related to the language definition it is always up-to-date (if the language engineering remembers to enter documentation). This documentation can basically include what the language engineer wants. So it can cover things like: how to find and identify the respective concepts from the system modeled, naming guidelines and other kind of way of working and way of modeling topics. If nothing is entered into the documentation MetaEdit+ provides minimum documentation based on the language concepts, their notation (shows icons for each concept), constraints, integration with other languages and available generators.

The above can also be exported to external formats in case e.g. documents of the modeling methods are needed. Some customers also export it to HTML pages that MetaEdit+ uses for manuals so the modeling documentation is then part of other possible guidelines. This all is nothing new and has been provided as a feature in MetaEdit+ for a long time (>10 years).

In addition we are also using models to document generators, both internally and especially when constructing languages and generators for customers – so that they can continue developing their generators further. We have a small graphical DSL for this purpose and to save modeling time we generate this model from implemented generators. To see the bigger picture, it is also common to create process models to show how the modeling process is integrated with the other development processes. For example, something like the process model in http://www.metacase.com/cases/architectureDSMatNSN.html.

Finally and as already mentioned by others too, sample models that act as references work nicely since they give context and imitating/copying others work is a common learning approach ;-)

• ▶ Reply