Generating documentation for model changes

[MattAdamson]

Does any know an effective way to produce RTF documentation which only documents changes to a model from one base line to another or the current model?

When were compiling designs for new changes to the application the key things we do are

1) Add / Remove classes from the model
2) Remove / Add / changes some existing methods / attributes on classes
3) Add / Remove some relationships from the model.

Rather than documentating say a full class and it's contents in the documentation which may span 10 pages, we'd rather just document the new methods added perhaps.

How do others handle this when they only want to document changes? This is key for us otherwise it will be all too easy for design reviewers to miss things if they can't focus on just the changes.

[Paolo F Cantoni]

Does any know an effective way to produce RTF documentation which only documents changes to a model from one base line to another or the current model?

When were compiling designs for new changes to the application the key things we do are

1) Add / Remove classes from the model
2) Remove / Add / changes some existing methods / attributes on classes
3) Add / Remove some relationships from the model.

Rather than documenting say a full class and it's contents in the documentation which may span 10 pages, we'd rather just document the new methods added perhaps.

How do others handle this when they only want to document changes? This is key for us otherwise it will be all too easy for design reviewers to miss things if they can't focus on just the changes.

If you actually save a baseline and then use the compare baselines functionality, you can save a log (actually an XML) of the differences.  You could (I presume) create an XSLT transform or write a little automation to parse the XML output and generate the documentation.

Actually, Sparxians, if you could release the XSD for the output, it would make it a lot easier to parse.

Let us know if you decide to take this route as we are interested in this also...

HTH,
Paolo

[«Midnight»]

Paolo,

Sparxians, if you could release the XSD for the output, it would make it a lot easier to parse.

Couldn't agree more. Please raise this as a suggestion, so people are aware of it. IMO this also should be dumped directly into the Sparx hopper though the Request-a-Feature page. I'll leave you to do that as the originator.

David

[MattAdamson]

Thanks for comments.

I presume you could easily generate an XSD from the XML file using any XSD tool such as Visual Studio .NET / XML Spy.

I haven't reviewed the automation interface for documentation generation, this sounds like a good approach though if we are very specific about what elements we want to document and still use a pre defined document template.

This still seems a pain though to do this for what should be a very common requirement. It's fine to document everything for new designs but maintainence and changes to design as we know takes the majority of the time through the lifecycle of an application.

[Nikhilesh_Kulkarni]

Hi,
I agree with the fact that documentation of new application would be much easier than documenting a maintenance work. During maintenance, you already have a baseline and users are interesting in documenting only that part which expects modifications. This documentation is used not only by designers and developers, but also by QA and other stakeholders  who may find it little complicated to read the changes thru XML or XSLT.

So if there is any way by which RTF/HTML document can be generated wrt the baseline (and not for entire application), that would be great.

I am interested to know if EA provices such facility.

[Paolo F Cantoni]

Thanks for comments.

I presume you could easily generate an XSD from the XML file using any XSD tool such as Visual Studio .NET / XML Spy.

I haven't reviewed the automation interface for documentation generation, this sounds like a good approach though if we are very specific about what elements we want to document and still use a predefined document template.

This still seems a pain though to do this for what should be a very common requirement. It's fine to document everything for new designs but maintenance and changes to design as we know takes the majority of the time through the lifecycle of an application.

Matt,

The baseline functionality has only really been in the product since v6.1.  I'm sure Sparx will be improving it over time.  However, in the interim, the data appears to be there in the XML.

The problem with reverse engineering an XML file is that the XSD so created is not a specification, it's a usage...  Thus the XSD you create from your XML may be different from the XSD I create from my XML.

(Just as dictionaries no longer tell you the meanings of words, just how they are used...  )

A proper XSD (from Sparx) is (should be) a normative specification and can be used for syntactic and semantic checks on the resultant XML.  Thus both of us can check that the two different XMLs we produce conform to the same XSD.

HTH,
Paolo

[«Midnight»]

I agree with Paolo:

The problem with reverse engineering an XML file is that the XSD so created is not a specification, it's a usage...  Thus the XSD you create from your XML may be different from the XSD I create from my XML.
...
...
...
A proper XSD (from Sparx) is (should be) a normative specification and can be used for syntactic and semantic checks on the resultant XML.  Thus both of us can check that the two different XMLs we produce conform to the same XSD.

If Sparx were to publish the XSD or XML Schema underlying their implementation, the rest of us could use it as part of the specification for components that need to interact with EA.

Nonetheless, I also agree with Matt's:

This still seems a pain though to do this for what should be a very common requirement. It's fine to document everything for new designs but maintenance and changes to design as we know takes the majority of the time through the lifecycle of an application.

This holds true for both his original context as well as what Paolo and I are speaking of. No need to overly complicate things (just yet).

David

[Weedman]

Now lets take this a step farther. I need to also change the requirements and use cases, etc...  When I generate the Use case text from activity diagrams I would like to have the new text (changes, additions, etc) be highlighted or something so that reviewers of the use cases can concentrate on the changes or additions.

The existing text needs to be there for contect purposes but reviewers do not need to review the existing text again.

It would be nice if the RTF generator allowed for conditionals in the formated output that could look at a create or modified date, or some other criteria and format the out put differently.

Jweedman

[colinc]

It is very manual, but couldn't you use the document generator option to  'only include objects modified since....' and keep a track of your release dates.

Unfortunately this is a date rather than a time, but it still it could help.

As for some form of macro language in the RTF generator, that would make life much simpler.  Many of us seem to be doing post processing, maybe if the API allowed hooks during RFT generation we could do have it happen on the fly?

Cheers Colin

Ps. Of course formatted text should go in there way earlier IMHO :-)