Documentation models

Perspective  ARCAD Observer
Access  Server >  Models

Documentation models define all the elements (chapter, sections) needed to create a documentation. The documentation model is the outline of the documentation contents, a set of chapters and sections, each presenting specific information that you choose. In documentation models, you also define the format and presentation for every chapter, section, body text and tables for the generated documents. The documentation model is then used as a template when creating documentations.

Step 1   In the ARCAD Observer navigator, open Servers > the desired server >  Documentation models.

Accessing documentation models

Result   The list of the documentation models is displayed in the  Documenter Models view.

ARCAD provides standard documentation models corresponding to a specific documentation issue. These standard documentation models can be duplicated and / or edited.

Standard documentation models

Application documentation
This type of documentation provides an overall documentation of applications.
Version documentation
This type of documentation provides an overall documentation of ARCAD versions.
List documentation
List documentation consolidates into a single document the contents of different lists created on the server. If you wish to analyze existing lists and use customization mechanisms, you can generate a genuine audit report.
Technical documentation
This type of documentation provides a general, non-detailed documentation. It is intended for those who wish to have an overall view of an application and the interactions between the different internal components.

There are two ways to create documentation models:

Follow the subsequent steps to create a documentation model.

Step 1   In the Documenter Model menu, click the  Create Model icon.

Step 2    Enter a name and a description for the new model in the model creation wizard. Click Finish.

Result   The documentation model is created and ready to be populated with chapters and sections.

Duplicating a documentation model enables you to quickly reuse the structure, without having to redefine the same documentation elements multiple times. When a documentation model is duplicated, the new model contains the same information as the original and can be edited to only change specific fields.

Typically, standard documentation models can be duplicated to customize a documentation type.

Follow the subsequent steps to duplicate a documentation project.

Step 1   In the Documenter Model menu, select a documentation model and click the  Duplicate Model icon.

Step 2    Enter a name and a description for the duplicated model in the model duplication wizard. Click Finish.

Result   The documentation model is duplicated and ready to be populated with the desired chapters and section.

Model plans are presented in an outline. The root contains the documentation type. First-level nodes represent chapters, and second-level nodes represent sections.

Each documentation type has a finite, pre-defined number of chapters and sections. For this reason, content management means choosing the elements that will appear in your documentation from the available elements. You can also define the order in which they will appear in your documentation.

When a model is created, all the chapters are included in the documentation model plan. You can then choose to delete the chapters that don’t match the objectives you have set and add the sections to the chapters you wish to keep.

Follow the subsequent steps to add a chapter to the documentation model.

Step 1    Right-click on the root node and select  Insert a Chapter in the contextual menu.

Step 2   select the chapter you wish to add in the Insert a Chapter options.

Note

The new chapter is inserted at the bottom of the list. Reorder the list of chapters using the Move the chapter up and Move the chapter down actions in the contextual menu.

Step 3   Save the changes (Click the Save the model icon, Ctrl+S or File > Save).

To remove a chapter, right-click on the chapter it in the model and select  Remove the chapter in the contextual menu.

Warning!

Removing the chapter will remove the sections defined in the chapter for the documentation model.

Follow the subsequent steps to add a section to the documentation model.

Step 1   Right-click on the chapter to which you wish to add a section and select  Insert a section in the contextual menu.

Note

If the chapter is empty, you can add all the sections available for that chapter type at once by selecting Insert a section > All sections.

Step 2   Select the section you wish to add in the Insert a section options.

Note

The section is inserted at the bottom of the list. Reorder the list of sections using the Move the section up and Move the section down actions in the contextual menu.

Step 3   Save the changes (Click the Save the model icon, Ctrl+S or File > Save).

To remove a section, right-click on the section it in the model and select  Remove the section in the contextual menu

Follow the subsequent steps to reorder the chapters and sections within chapters.

Note

If you move a chapter, all associated sections will move with it.

Step 1    Right-click on a chapter or a section in the model and select the  Move Up and  Move Down actions in the contextual menus.

Step 2   Save the changes (Click the Save the model icon, Ctrl+S or File > Save).

Note

Custom chapters can also be added to the documentation model. They can be populated with custom sections. All the custom chapters' and sections' title, content and format can be modified.

  • General description
  • Operational attributes
  • Application naming convention
  • Linked applications Sub-systems
  • Functions
  • Sub-functions
  • Field dictionary
  • Versions
  • User functions
  • Application variables
  • Procedure repository
  • Literals repository
  • Libraries
  • IFS directories
  • Customized section
  • Detailed description
  • Functional description
  • Function tree
  • Homonyms
  • Versions
  • Input/output diagram
  • File cross references
  • Modified fields (by file)
  • Call chain
  • Called programs
  • Calling programs
  • Procedure
  • Maintenance reports
  • Copy clauses
  • Message identifiers
  • ILE links
  • Development folder
  • Customized section
  • Detailed description
  • Functional description
  • Function tree
  • Homonyms
  • Versions
  • Fields
  • Primary keys
  • File utilization diagram
  • Cross references on programs
  • Maintenance reports
  • Database relationships diagram
  • Information on database links
  • Dependent files
  • Message identifier
  • Trigger
  • Customized section
  • Detailed description
  • Functional description
  • Function tree
  • Homonyms
  • Versions
  • Maintenance reports
  • Message identifiers
  • Customized section
  • Detailed description
  • Functional description
  • Child versions
  • Integration log
  • Development team
  • Test team
  • Maintenance reports
  • Modified components
  • Customized section
  • Detailed description
  • Element list
  • Customized section

Now that you have defined the elements that will appear, and their order, you will set up your document’s format.

Formatting depends on the display type used by the element to present its information. There are three major display groups: Text display, table display, and diagram display. Each of these groups corresponds to specific formatting settings.

Even if all of the elements in the documentation use one of these three display groups, some may still offer additional information inherent to the information they represent.

Define here the document title, a document description as well as the title of each chapter or section.

Note

The document Title is different from the documentation model identifying name defined when creating the documentation model.

The document title is by default the same as the name of the model. Changing the documentation title has no impact on the documentation model identifier set in the definition section.

Documentation models titles

Follow the subsequent steps to to define a document title, ad chapter title or a section title:

Step 1    Click on the node in the documentation.

Step 2   Enter a title appropriate to the description of the selected element.

Step 3   Save the changes (Click the Save the model icon, Ctrl+S or File > Save).

Define how the information will be displayed.

Documentation models layout

Select the color and font of the titles, labels and text body for the documentation. You can also choose the background color for titles and text body.

  • Titles (for the document title, chapters and sections titles)
  • Layout for the aggregate title (at chapter level)
  • Headers (for sections with tables)
  • Body text

Text formatting options

Click the Background color button to open the standard color selection dialog. Select a color or define a custom one. Click OK.

Formatting options - background colors

Click the Fonts... button to open the standard font selection dialog. Define the format (text color, font, size, etc.) of the text. Click OK.

Formatting options - Fonts

Save the changes (Click the Save the model icon, Ctrl+S or File > Save).

For each table, ARCAD Observer provides the option of choosing the columns displayed, as well as their position, size, and the header text to show.

Documentation models tables layout

For the sections of the documentation model presented as a table, the table's layout properties are found in the Column Properties tab in the contextual Parameters of the section.

  • To show or hide the column in the final table, click to select the column in the list and check or uncheck the Visible box.
  • To modify the header text for your column, click to select the column in the list and enter a new value in the Alias entry field.
  • To modify column size, click to select the column in the list and enter a value in the size entry field or use the field’s increment arrows. The Available Size field shows you the remaining size available as a function of the modifications you have made.
Note

Column size is specified as a percentage of overall table size. This is why column value must be between 1 and 100.

  • To modify the order of your column’s appearance in the table, click to select the column you wish to move and click the  or  icons to move the column up or down.

Save the changes (Click the Save the model icon, Ctrl+S or File > Save).

In addition to the documentation plan and documentation formatting, some optional parameters are available for the documentation model.

These options are available for some of the sections of the model. They can be found in the Options tab in the contextual Parameters of a section.

Documentation models options

ARCAD Observer offers the option of including functional field descriptions. This option is available for:

  • Field dictionary in the Application description chapter;
  • Modified fields (by file) in the Program description chapter;
  • Fields in the File description chapter.

Check the Include functional description box in the Options tab.

Important!

Printing the functional description has a significant impact on the field documentation. Use this option sparingly.

Defining a call tree involves defining the different calculation levels.

Select a calling chain type from the drop-down menu:

  • Ascending calling chain
  • Descending calling chain
  • Ascending and descending calling chain

ARCAD Observer offers you the option to display in the documentation the call parameters headings between two programs.

Check the Display call parameters heading box in the Options tab.

ARCAD Observer offers you the option to display in the documentation the used keys for the cross-references. This option is available for:

  • File cross-references in the Program description chapter;
  • Cross-references on programs in the File description chapter.

Check the Display used keys box in the Options tab.

ARCAD Observer offers you the option to define the maximum size of the file utilization diagram in the documentation. Enter a value for the diagram size Max. length and Max. height in the section's layout tab.

For message identifiers, you can request the messages to be sorted by sequence numbers. This option is available for the Message identifiers section in the Program, Files and Other components description chapters.

Check the Sort by Sequence Number box in the Options tab.

Important!

These options are only available for Version description chapter's maintenance reports. Other maintenance reports for Program, Files and Other components description chapters follow a standard layout and have no options.

Check the corresponding boxes to include or exclude items in the Maintenance Report's Information.

Workload
Estimated load and real load.
Schedule
Opening and closing dates.
Qualification
Maintenance type and action type.
Managers
Change manager and project manager.

To include the incident reports associated with a version, check the Display incident reports box in the Incident report tab of the section's parameters.

To include a table of components impacted by a version, check the Display the components table option in the Components tab.

Warning!

Deleted documentation models cannot be accessed or recovered

To delete a documentation model, either right-click on the item in the Documenter Models view and select  Delete, or select the item and click the Delete icon in the toolbar. Click OK to confirm or click Cancel to keep the documentation model in the dialog.