The Model Driven Software Network

Raise your level of abstraction

At my current client we are in the process of documenting the modelling method.
At the moment we have some Word documents scattered around the intranet and some network drives, we have a partial metamodel in Enterprise Architect, some powerpoint slides... you get the picture.
I would like to rationalize this approach and have a central integrated documentation. This documtation should include all aspects of the modelling method, and it should be able to link from one aspect to the other.
To get an idea of what I mean with the different aspects see
The different types of documentation I need are described here:

The only tool I found so far that seems to be able to provide what I need is EPF but I'm not sure whether that will fit my needs. I'm afraid it will be a bit overkill.

So my questions are:
- How do you document your (Modelling) method
- Are there any other tools on the market that I could use.



Views: 115

Reply to This

Replies to This Discussion

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.

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?!


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.

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.

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!

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

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




© 2018   Created by Mark Dalgarno.   Powered by

Badges  |  Report an Issue  |  Terms of Service