It is much more productive to press a button to generate:

1. a new version of a large specification document consisting substantially of information from a UML model than it is to cut and paste the modified diagrams and update supporting text manually.
2. up to date internet/intranet pages showing the latest analysis, design and implementation diagrams and details than maintain the HTML and image files manually.
3. reports summarizing key aspects of a model than to collate the information manually from one or more models

Text with Models

Many teams or organisations start their modelling journey by including adhoc diagrams to support textual descriptions of static and dynamic aspects of a design.

This mix of adhoc diagrams and textual descriptions traditionally form a specification document. When managing requirements in a purpose-built tool like MicroFocus's CaliberRM, the diagrams and text may be embedded in, or attached to entries representing use cases or other types of requirement. Feature-Driven Development (FDD) , Scrum or eXtreme Programming projects may store adhoc diagrams and text as attachments of a feature or user story.

Adhoc diagrams frequently suffer from a lack of consistent, unambiguous notation. Sooner or later, an organisation realises that time spent deciphering the adhoc notation in their design diagrams is significant. Understanding may be increased, and mis-communication reduced if everyone uses the same notation. Rather than invent their own notation, this frequently means adopting an industry standard graphical notation such as the Unified Modeling Language (UML) from the Object management Group (OMG).

Frequently, this move to a standard notation is matched by a desire to move away from using general-purpose diagram editing tools like those built into Microsoft PowerPoint to a purpose-built modeling tool. These tools not only make it easier to build industry standard compliant models but also typically enable the generation of skeleton source code and basic reports.

However, the production of web- or paper-based specification documents based on these models still frequently consists of copying and pasting, or importing by some other means, diagrams into the documents to support textual descriptions.

This approach to modeling is often referred to as the 'Text with Models' approach [Kleppe].

Models with Text

Once a team or organisation has established the use of an industry standard notation, the next big step forward is to switch from the copying and pasting of diagrams into documents to generating large sections of documents directly from the models.

Here, instead of creating models and diagrams to support textual descriptions, modelers add textual descriptions to elements and diagrams in the model. They then use a template or script-driven generation tool to generate whole specification documents, or more usually, the reference sections of specification documents. 

Not only does the generation of documents significantly reduce the tedious manual formatting of large documents and time-consuming manual updating, it also enables different formats and levels of detail to be included in different documents aimed at different audiences. The same information may even be presented in different file formats such as HTML, PDF, and RTF, for example.

This is often referred to as the 'Models with Text' approach [Kleppe].

In practise, this approach requires a modeling tool with sophisticated document generation capabilities. There is a small but significant upfront cost in developing the documentation generation templates or scripts if those supplied with the product do not fully meet the requirements of a team or organization.

However, where the longer term cost savings and productivity benefits could outweigh the initial investment by an order of magnitude or two, the 'Models with Text' approach clearly makes sense.

MicroFocus Together includes a powerful documentation generation engine and document template designer. These are commonly referred to as the product's gendoc features. It is capable of generating documents in plain text, RTF, PDF, HTML and even XSL-FO file formats.

Together's gendoc engine can take one or more Together projects as input and, where multiple projects are used, these can contain any combination of UML 1.x, UML 2.x, BPMN and ERD models. This also includes Together's UML-based design pattern definition and profile definition projects. This means that gendoc can generate documentation for the Together-based design patterns and UML profiles as well as for the models in which they are used.