Creating professional documentation

[Molto Mike]

Hey,

I am trying to use EA for creation of system documentation. IMHO, the RTF template shipped has some major flaws, and the HTML template is also only useful to a limited degree.

Looking at how those templates can be modified, I find it somewhat hard to believe that people invest much of the time needed to tweak those. Especially, since I am not even sure that some of the things I would like to see changed can be done through the templates, but maybe I just don't find the code to change...

So I am wondering, how you guys are creating documentation, maybe docs that are even going to be used by 3rd parties. Are you customizing the templates, are you doing Word Macro magic on the produced RTF, or are you using the automation API?

In case you customized your templates, is there a chance you share them, or show some sample output? I am just really curious, what is possible using the different approaches.

Sure, using the automation API gives all options, but that is pretty much like starting from scratch...

Any insights are appreciated,
Mike

[PhilR]

We are well advanced into a project which plans to produce client documentation directly from EA.  The approach we have taken is to use the RTF generator combined with Word macros.  Not elegant but it works and only required a modest investment of time.  We did a bit of up front planning as to how to organise our project stucture so it looks good in the final documents.

In general terms I can see a number of options for generating custom documentation.

1) Use the automation interface - undoubtedly the best in the long run but requires a knowledge of VB (which I don't have)
2) Use the standard RTF generator with Word Macros (as described above)
3) Dump the project to XML and generate the documentation from the XML.  I believe that PHP would make a great tool for this job (probably because I do know PHP!) but have not tried it yet.  This approach is vunerable to changes in the stucture of the XML file but since it is based on a standard (XMI) the core UML feature should be OK.
4) Open the .eap file in MS Access and develop reports based on the underlying tables.  This approach is not to be recommended because the structure of the underlying tables may change but it might get you out of a serious hole once in a while.  Also you must make sure the tables are opened read only or else documentation will be the least of your worries.

There is one other approach based on the automation interface which I have played with a bit.  PHP has a COM object interface and it appears possible to use the automation interface from PHP.  Combine this with a web server and you can have online access to the EA repository via a browser.  

Add HTMLDoc and you can even generate postscript and pdf files from the HTML!

See
www.php.net
www.easysw.com/htmldoc/

Happy Documenting

www.easysw.com/htmldoc/

[Molto Mike]

Since you did not even mention it, are you implying that the RTF and HTML template mechanism of EA is not worth the trouble?

Mike

[PhilR]

Did ramble on a bit didn't I?

I can imagine using the HTML template (because I know HTML) but RTF - spare me.

Phil

[mch]

Hi,
also struggling with this problem. I would like to see some easier customisation of the RTF templates available. The API option is ok but I would need a lot of time upfront to learn how to use it - maybe time to upskill in Java?
Anyway on current projects we are producing interim releases in HTML and only generating the formal documentation at key milestones. I've got a template with standard cover pages, organisation, and styles. I use the RTF generator to extract the docs and then attach the template to the generated output file. From there I manually adjust as required.
The overhead needed to create and maintain an automated approach is fairly high, an afternoon every now and again putting a formal document together is a viable alternative. That being said I would still like to see easy customisation.
Cheers,
Mark