Generating Documentation with Together

The Document Generation engine within Together has not had the attention it deserves over the last decade. Its user-interface is not particularly user-friendly and its user documentation is woeful.

However, for those that have to produce specification documents from their models, it can still be a huge time saver if it can be understood and made to work. Hopefully, the following can help with this task:

• Introduction to Generating Documentation
  One of the key ways of producing value from a UML modeling tool is being able to generate wide variety of documents and reports in differing formats from one or more models.
  Read the full article...
  
  
• Creating a New Documentation Template in Together
  To create a new document generation template file, select File|New|Other… from Together’s main menu bar...
  Read the full article...
  
  
• The Structure of a Together Document Generation Template
  Each and every template (tpl file) is made up of a number of sections. These sections come in various flavours...
  Read the full article...
  
  
• Together Document Generation Template Static Sections and their Controls
  Together Document Generation Template Static Sections contain one or more controls of various types.
  Read the full article...
  
  
• Looping with Element Iterators
  When the document generator encounters an element iterator, it repeatedly processes the sections nested within that iterator for each of the model elements and diagrams that meet the criteria specified in the element iterator’s properties.
  Read the full article...
  
  
• Looping with Property Iterators
  In Document Generation Templates generate content from model element and diagram properties by looping through them with a Proprty Iterator section.
  Read the full article...
  
  
• Folder sections
  Folder sections group other sections together within a Together Document Generation Template.
  Read the full article...
  
  
• Calls to stock sections
  These chunks of template can be reused in multiple places within a main Together Document Generation Template.
  Read the full article...
  
  
• Calls to Template Sections
  A Together Document Generation Templatecan contain one or more calls to another template file
  Read the full article...
  
  
• If-Then-Else with Enabling Conditions
  If an enabling condition in a Together Document Generation Template evaluates to true then the document generator processes the section. If the expression evaluates to false then the section is ignored.
  Read the full article...
  
  
• Of Tables, Panels and Stock Sections
  Element iterators, property iterators, and folder sections by default use an output style they call Paragraph Flow. However, there are two other output styles available, one of which is Table Flow.
  Read the full article...
  
  
• Delimited Output Style
  As well as the default paragraph output style, and the table output style described above, iterator and folder sections may also be set to Delimited Text Flow output style.
  Read the full article...
  
  
• Generating Hyperlinks
  It is possible to create hyperlinks from one part of a generated document to another. This works when generating either HTML or RTF file formats but not for PDF, XSL-FO, and obviously not for plain text file format. It is also possible to create hyperlinks in the generated documents that link to external files and URL’s.
  Read the full article...
  
  
• OCL Expressions and Metamodels
  As a standard query and expression language within a tool like Together, OCL seems to have found a genuine usefulness.
  Read the full article...
  
  
• Customized and Programmed scopes in Element Iterators
  There are times when even the numerous options available in the Default method of Collecting elements are not flexible enough.
  Read the full article...
  
  
• Master / Slave Documents
  When generating a large specification document, there may be significant sections of free-form text that support the more reference-oriented sections generated from a model.
  Read the full article...
  
  
• Framesets
  The Together gendoc engine is capable of producing a set of frames-based HTML pages. To do this a special frameset template needs to be created and the layout of the desired frames configured in the template properties dialog.
  Read the full article...
  
  
• Template Management and Distribution
  The organisation of the template files that ship with Together follow asimple convention.
  Read the full article...
  
  
• Modeling Techniques for Document Generation
  There are a number of patterns and strategies that can be used when creating UML models in Together that can make it easier to generate the required documents.
  Read the full article...
  
  

Together's gendoc facility provides a powerful and flexible means of generating documents in various formats. This in turn provides the opportunity for an organisation, department, or team to start to move up from the 'text with models' paradigm to the 'models with text' paradigm.

Gendoc can also play a powerful role as a component in a model-driven development, engineering, or architecture (MDD, MDE, MDA) approach especially when combined with an organisation's design standards covering how models should be built, and audits and metrics that enforce those rules, guidelines, and conventions.