Publishing Documentation Tooling Requirements
with thanks to Gregg Seppala Model Documentation Tooling Requirements:
Woody: A Walk-thru is NOT the same as a list of attribute and class descriptions, no matter how well formatted. Very simply, at the DMIM level, the discussion of the class needs to be "abstract". The walk-through text should be attached to the staticModel (the DMIM), and the MIF provides for this. Unfortunately, at present, the Visio tool does not give us a place to lodge this, and thus the PubDb is the only place to anchor it.
Meade: Where committees have created functioning DMIMs, there is a real duplication problem if they document both DMIM and RMIMs. Personally, I would rather see the descriptions in the RMIMs, because those are the things I actually use. However, logic suggests that it is more reasonable to put the descriptions in the DMIM. [Perhaps we should put having descriptions from DMIMs appearing in RMIMs onto our tooling wish list. However, if we do that, I would urge us not to build such a feature into the actual guidance that is provided to committees.
Hugh: Because I'm wary of the robustness of the documentation methods in Visio we are doing this in an excel spreadsheet. We will then cut and paste this into the Visio tooling (or anywhere else we are told to) to generate some detailed documentation at class and attribute level. I believe the right sequence for doing this is get the DMIM right and then work back and forward with the RMIMs until everything is consistent between DMIM and RMIM. Tooling to import and export the documentation between Visio drawings and an Excel spreadsheet (or Access database) would be a great help.
Lloyd: We've done all of our pan-Canadian standards using the Visio tool directly and have had very few problems with things disappearing (None at all within the last year and a half I'm aware of). Also, if you've got your source checked into SVN, it's relatively straight-forward to go back and copy and paste what you need out of the XML if you toast something by accident. Given that we're hoping to migrate to Eclipse when the NHS has finished the port, I'm not sure it makes much sense to invest in a new tool.
Virginia: the attribute descriptions added using the RMIM designer are exposed on the table views (and I believe the excel views) but there is no “pretty” way to see that doc. So it could be that we need a different (or additional) way to publish the attribute descriptions in the ballot.
Gregg: A tooling request would be for us to be able to enter class, association and attribute documentation in the D-MIM and then inherit that in each derived R-MIM where it can be left as is or edited to reflect the context. I do this now but (a) there is no easy way to see or edit documentation for the full model and (b) the only way to "inherit" is to rebuild each R-MIM from scratch for every change.
Patrick: (paraphrasing from discussion on call) Need ability to see and edit documentation for complete model rather than current element at a time view provided by RMIM Designer.
