How do you document your (Modelling) Method?

[Geert Bellekens]

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 Modelling Method
The different types of documentation I need are described here: Modelling Method Documentation

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.

Thanks

Geert

[beginner]

I usually document this with UML. And because it's handy I use EA as tool. The process documentation is done with the Analysis profile that comes with EA. Use Cases would be desirable but (as usual) there's no time for that. The domain analysis is taken as basis for an individual profile. My current customer is using the V-Model. You can take the single Activities and fill them with actions and related deliverables.

I try to document all that stuff in all my projects. Though management usually tries to block the related effort they finally are very happy with that sort of documentation.

I never would think of a different tool for such a job. Or maybe I misunderstand your question?

b.

[Geert Bellekens]

For documenting the Meta model EA is fine, that is what I use as well, but as a documentation tool it is a bit limited.
I need things like

• User manual -> linear document that needs to suitabe for printing
• Reference documentation -> something like the metamodel
• Training documentation -> linear slides for a specific topic
• Delivery specification -> Word Templates
• Examples -> actual models that are a good example of a specific topic
• ...

And all of that should be available in an easy to reach location (such as an intranet).
Plus each of those types of documentation should be linked to the topic topics they speak about.
If I have a training slide about usecases then I should be able to go from that slide to the usecase element in the metamodel, to the process that delivers the usecases ("gather requirements"), to the deliverable template that is used, to the rules and guidelines about usecases, to the definitions of the related artifacts such as actors... you get the picture.

I'm not sure EA is really suitable for that task, and I don't want to spend too much time creating addins and stuff just to make it work with EA when there are other tools on the market that already provide what I need out of the box.

Geert

PS. Actually personally I would love to build all of this around EA, but I'm afraid my client won't be that keen to pay for all of that 8-)

[beginner]

things like

• User manual -> linear document that needs to suitabe for printing
• Reference documentation -> something like the metamodel
• Training documentation -> linear slides for a specific topic
• Delivery specification -> Word Templates
• Examples -> actual models that are a good example of a specific topic
• ...

Actually I'm building (most) of above documentation directly from EA. The trick is, not to get swamped with all that M$-RTF stuff. I personally use TeX since many years and with a bit of automation you can produce GOOD documentation. You may have to take a (huge - depends on your current stand) step. But once you've taken that you'd never go back.

Samples/templates (of course) are best placed in EA. You can export XMI and import with strip GUID, thus making identical copies.

b.

[Geert Bellekens]

Beginner,

I don't think it will really make a difference whether I write my document generator targetted at MS Word or TeX, or any other format. The effort will still be pretty similar.

I'm certainly not considering using the build-in documentgenerator in EA as that would be way too limited for my purposes, and it would restrict me to a single type of output.
Using a decent tooling framework design I'm sure I can re-use most of my generator for the different output types (Word, HTML, ...)

Geert

[beginner]

There's no need to evangelize TeX users. There's no chance to evangelize RTF users. I'm no evangelist anyway.

b.