You use Documtr in MDriven Designer to write rich documentation for model artifacts and publish the model and its documentation as an XPS report.
Document model artifacts
Documtr stores rich-text documentation with the artifacts you create in your model. Use it to record the purpose, background, and design decisions for classes, attributes, associations, methods, diagrams, and other model elements.
For example, document a House class with an explanation such as This is where tenants live, document a Location class as a geographical place, and document an association end to explain what ownership means in the domain.
Documentation is part of the model knowledge. It complements the shorter code comments available on model artifacts; published documentation can include both the rich text you write and code comments.
Write documentation in the DOC tab
The DOC tab is the focused editor for the item currently selected in the MDriven Designer model surface.
- Select an artifact in the model, such as a class, attribute, association, or diagram element.
- Open the DOC tab.
- Enter or edit the rich-text documentation in the editor.
- Select another artifact to document it. The DOC tab changes context to show the documentation for the newly selected item.
The editor supports rich text, so you can use formatting where it helps readers scan the documentation. Keep the content specific to the selected artifact. For example, explain why an association exists and what each end represents rather than repeating the name of the association.
Use the Documtr window for an overview
Open the Documtr window when you want to review and edit several documentation snippets in the current context. On a class, you can use Ctrl+D to open it.
The window shows multiple documentation fields together. This gives you an overview of the documentation for the selected model context while keeping an editor available for the selected field.
- Select an artifact in the model surface.
- Open Documtr, for example by selecting a class and pressing
Ctrl+D. - Review the documentation snippets displayed for that context.
- Double-click a field to edit its documentation in the editor on the right.
- Leave the Documtr window open while you move through the model. It follows your selection and updates its context.
This workflow is useful when documenting a class and its related attributes, methods, and associations in one pass.
Publish a FlowDocument and save it as XPS
Documtr can compile the model content and its documentation into a FlowDocument. You can then save that document in XPS format for distribution as a fixed-layout model report.
- Complete or review the documentation for the artifacts you want to publish.
- Open the Documtr window.
- Select Publish Flowdocument at the top of the window.
- When prompted, choose where to save the generated report.
- Save the FlowDocument as an
.xpsfile.
The published report provides an architecture-oriented view of the model. It can include model diagrams, the rich documentation entered through Documtr, and code comments associated with model elements.
Suggested documentation practice
Use documentation at the level where a reader needs the explanation.
| Artifact | What to document | Example |
|---|---|---|
| Class | Its responsibility in the domain | House: Represents the place where tenants live.
|
| Attribute | Meaning, units, source, or business rule | Address: The street address used to identify the house.
|
| Association or association end | The relationship and the role at each end | owner: Identifies the person responsible for the house.
|
| Diagram element | The design purpose of the diagram or area of the model | This diagram describes how houses, tenants, and locations are related. |
Write enough detail that a reader can understand the model without relying on the original modeller's memory. Use code comments for short explanations and Documtr rich text for fuller background and design rationale.
Scope
Documtr documents the model and produces an XPS model report. It is separate from data-driven application reporting with OpenDocument and Microsoft Office templates. For those reports, see OpenDocument and Microsoft Office report generation.