Documentation versions

Perspective  ARCAD Observer
Access  Server >  Applications > Application Name >  Documentation >  Versions

Once a documentation project is set up for you application, you create a first version of the documentation. Your documentation can then be updated, by creating new version of the same documentation.

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

Step 2   In the list of applications, open the desired application.

Step 3   Open Documentation > the desired documentation project > Versions.

Accessing documentation versions

Step 4   The list of the versions that already exist for the documentation project is displayed.

Each documentation project comes in versions. To get started with a documentation project, you need to create the first version of it. There are two ways to create a version, either create a new documentation version or duplicate and edit and existing one.

Follow the subsequent steps to create a documentation version.

Step 1   In the ARCAD Observer navigator, open the desired documentation project.

Step 2   Right-click the Versions node and select  Add a documentation version.

Result   The Creating a documentation version wizard opens.

Step 3   Fill in the fields in the dialog:

Start date
Specify the version opening date. By default, this is the current date. To modify, click the calendar icon to open the date selection dialog. Select a date by clicking a day on the calendar. The date highlighted in red is the current date.
End date
Specify the version closing date. To modify, click the calendar icon to open the date selection dialog. Select a date by clicking on a day on the calendar. The date highlighted in red is the current date.
Version number (Mandatory)
The documentation version number uses a three-parts version number: the major number, the minor number, and the sub-version number. Enter a numerical value for each of these parts, or use the increment arrows. It is not possible to create a version if the version number already exists for the documentation project.
Note

This version number must be unique within each project.

ARCAD Observer verifies that a version associated with a project underway does not have the number you specified.

Query level

Select a query level in the drop-down list:

  • *LASTPRD: the level used is the one of the application's last transfer to production.
  • *LAST: the level used is the one of the last update of the cross-references for each component.
  • *CURENV: the components version level is the one on which you were initialized.
  • Version number: the specified level is used.
Description
Enter a short description of your version. This description field is limited to 255 characters. The description is displayed between parenthesis in the ARCAD Observer navigator.
Comment
Enter a long description, not limited in number of characters, which provides a full description of the contents and objectives of the new version.
Project manager
Select one of the ARCAD Observer system user referenced in the drop-down list.
Model (Mandatory)
Select the reference model to be used for your version. Use the down arrow to access different models defined with the Model view.

Step 4    Click Finish.

Result   The new documentation version appears under the Versions node of the documentation project.

Creating a document version by duplicating an existing one is a specific creation operation. It allows the creation of a new version by using a copy of an existing version model. It is also possible to recover the component list and documentation contents.

Note

Besides its practical aspects, this operation is very useful for updating the version, as you will see further in this document.

Follow the subsequent steps to duplicate a documentation version.

Step 1    Select the version you wish to duplicate from the project management tree.

Step 1   In the ARCAD Observer navigator, open the desired documentation project.

Step 2   Right-click the documentation version and select  Duplicate in the contextual menu.

Result   The Duplicate a documentation version wizard opens.

Step 3   Fill in the fields in the dialog:

Start date
Specify the version opening date. By default, this is the current date. To modify, click the calendar icon to open the date selection dialog. Select a date by clicking a day on the calendar. The date highlighted in red is the current date.
End date
Specify the version closing date. To modify, click the calendar icon to open the date selection dialog. Select a date by clicking on a day on the calendar. The date highlighted in red is the current date.
Version number (Mandatory)
The documentation version number uses a three-parts version number: the major number, the minor number, and the sub-version number. Enter a numerical value for each of these parts, or use the increment arrows. It is not possible to create a version if the version number already exists for the documentation project.
Note

This version number must be unique within each project.

ARCAD Observer verifies that a version associated with a project underway does not have the number you specified.

Query level

Select a query level in the drop-down list:

  • *LASTPRD: the level used is the one of the application's last transfer to production.
  • *LAST: the level used is the one of the last update of the cross-references for each component.
  • *CURENV: the components version level is the one on which you were initialized.
  • Version number: the specified level is used.
Description
Enter a short description of your version. This description field is limited to 255 characters. The description is displayed between parenthesis in the ARCAD Observer navigator.
Comment
Enter a long description, not limited in number of characters, which provides a full description of the contents and objectives of the new version.
Project manager
Select one of the ARCAD Observer system user referenced in the drop-down list.
Model (Mandatory)
Select the reference model to be used for your version. Use the down arrow to access different models defined with the Model view.

Step 4   Click Next > to continue.

Step 5    Check the Duplicate the component list, the Duplicate the version list and/or the Duplicate the list of lists box to recover the lists.

Step 6    Check the Duplicate the documentation box to recover the documentation's contents.

Step 7    Click Finish.

Result   The new documentation version appears under the Versions node of the documentation project.

Once you have created a documentation version, you can modify its general properties. However, it is impossible to edit the properties if the version is closed.

Follow the subsequent steps to edit the properties of a documentation version.

Step 1   In the Documentation node of the Navigator, right-click on the desired version and select  Properties.

Result   The Properties window of the documentation version opens.

Step 2   Edit the fields in the dialog:

Start date
Specify the version opening date. By default, this is the current date. To modify, click the calendar icon to open the date selection dialog. Select a date by clicking a day on the calendar. The date highlighted in red is the current date.
End date
Specify the version closing date. To modify, click the calendar icon to open the date selection dialog. Select a date by clicking on a day on the calendar. The date highlighted in red is the current date.
Version number (Mandatory)
The documentation version number uses a three-parts version number: the major number, the minor number, and the sub-version number. Enter a numerical value for each of these parts, or use the increment arrows. It is not possible to create a version if the version number already exists for the documentation project.
Note

This version number must be unique within each project.

ARCAD Observer verifies that a version associated with a project underway does not have the number you specified.

Query level

Select a query level in the drop-down list:

  • *LASTPRD: the level used is the one of the application's last transfer to production.
  • *LAST: the level used is the one of the last update of the cross-references for each component.
  • *CURENV: the components version level is the one on which you were initialized.
  • Version number: the specified level is used.
Description
Enter a short description of your version. This description field is limited to 255 characters. The description is displayed between parenthesis in the ARCAD Observer navigator.
Comment
Enter a long description, not limited in number of characters, which provides a full description of the contents and objectives of the new version.
Project manager
Select one of the ARCAD Observer system user referenced in the drop-down list.
Model (Mandatory)
Select the reference model to be used for your version. Use the down arrow to access different models defined with the Model view.
Important!

You cannot edit the Version number and the Model. If those fields are not correct for the version created, you have to delete it and create a new one with the right Version number or Model.

Step 3   Click OK.

Result   The properties are edited. You may need to refresh the ARCAD Observer navigator to see the modifications to the description. Right-click the Versions node and select  Refresh.

When the version is created, the version editor opens with the version structure documentation. This structure comes from the model selected before. At this stage, it is still possible to change the structure (Add, Delete, Move items). However, it is not possible to select a new model for the plan. Modifications to the documentation plan does not affect the documentation plan of the model.

Reference

Refer toEditing documentation model plans.

The documentation version plan editor

When the version is created, the format and layout from the model selected before. At this stage, it is still possible to change the format and layout for each chapter, sections or tables. The format and layout editor is the same as the one used to create the model. Modifications to the documentation layout and format does not affect the layout and format of the model.

Reference

Refer to Editing document model's layout and format.

First, it is necessary to select in the version the elements to be documented. These elements can be Components, ARCAD Versions, and/or ARCAD Lists. The process is the same for components, versions or lists, you retrieve the lists of items you wish to document.

Note

It is possible to use items from Components tab, version or list in the same documentation.

The list of components to document

Components can be imported in four different ways:

In this case, a window allows to choose an ARCAD list of components to proceed.

Step 1   In the List of components to document tab of the documentation editor, right-click in the list section and select  Import from a list in the contextual menu.

Step 2   Select the list to document. Navigate in the Lists node of the connected server in the dialog and click the desired list. You can document several ARCAD lists of the application but you have to select one after the other.

Click Next > to continue.

Step 3   Select the merge options.

Tick to Merge this imported list with the existing list.

Tick to Sort the entire list after the objects are added.

Click Finish.

Result   The list of components is displayed in the editor.

The components stored is the work list will be added as components to document.

To import from the current worklist, right-click in the list section of the List of components to document tab of the documentation editor, and select  Import from the current work list in the contextual menu.

In this case, a window displays a selection filter to choose the components.

Step 1   In the List of components to document tab of the documentation editor, right-click in the list section and select  Import from a repository in the contextual menu.

Step 2   Use the filters to refine the list of components.

Click Next > to continue.

Step 3   [Optional] Select one or several functions to restrict to specific functions of the application. Click on the functional module and the click the [> >] button.

Important!

Only components that belong to one of the specified branches appear in the list of impacted components.

Click Next > to continue.

Step 4   Select the merge options.

Tick to Merge this imported list with the existing list.

Tick to Sort the entire list after the objects are added.

Click Finish.

Result   The list of components is displayed in the editor.

A window allows you to choose an ARCAD version with the components to proceed.

During the merge, ARCAD Observer compares the list of components from the ARCAD version and the list of components from the base ARCAD version.

  • New components are added to the corresponding chapters, depending on their types.
  • Content entries associated with the deleted components are deleted.
  • Information regarding the components marked Checked Out or Modified are deleted but the contents entries are kept.

Step 1   In the List of components to document tab of the documentation editor, right-click in the list section and select  Import from a version in the contextual menu.

Step 2   Select the version in the drop-down list. Click Next > to continue.

Step 3   Use the filters to refine the list of components.

Click Next > to continue.

Step 4   [Optional] Select one or several functions to restrict to specific functions of the application. Click on the functional module and the click the [> >] button.

Important!

Only components that belong to one of the specified branches appear in the list of impacted components.

Click Next > to continue.

Step 5   Select the merge options.

Tick to Merge this imported list with the existing list.

Tick to Sort the entire list after the objects are added.

Click Finish.

Result   The list of components is displayed in the editor.

To remove a component from the List of components to document, right-click the component in the list section of the editor and select  Remove in the contextual menu.

The list of versions to document

It is possible to import All the ARCAD versions, or to Select a range of versions.

Step 1   In the List of versions to document tab of the documentation editor, right-click in the list section and select  Import in the contextual menu.

Step 2   Select the version to document. You can document several ARCAD versions of the application.

Tick All to document all the application versions.

Tick Select a range of versions to document only a sub-set of versions. In this case, you should define the upper and lower limits of this set by selecting their values from the drop-down lists provided (From Version and To Version).

Note

The limits are included in the set to be documented.

Click Next > to continue.

Step 3   [Optional] Select one or several functions to restrict to specific functions of the application. Click on the functional module and the click the [> >] button.

Important!

Only components that belong to one of the specified branches appear in the list of impacted components.

Click Next > to continue.

Step 4   Select the merge options.

Tick to Merge this imported list with the existing list.

Tick to Sort the entire list after the objects are added.

Click Finish.

Result   The list of versions is displayed in the editor.

To remove a version from the List of versions to document, right-click a version in the list section of the editor and select  Remove in the contextual menu.

The list of lists to document

Lists can be imported in two different ways:

Note

It is possible to import more than one list.

The components stored is the work list will be added as components to documents.

To import from the current worklist, right-click in the list section of the List of lists to document tab of the documentation editor, and select  Import from the current work list in the contextual menu.

In this case, a window allows to choose an ARCAD list of components to proceed.

Follow the subsequent steps to import from an ARCAD list:

Step 1   In the List of lists to document tab of the documentation editor, right-click in the list section and select  Import from a list in the contextual menu.

Step 2   Select the list to document. Navigate in the Lists node of the connected server in the dialog and click the desired list. You can document several ARCAD lists of the application but you have to select one after the other.

Click Next > to continue.

Step 3   Select the merge options.

Tick to Merge this imported list with the existing list.

Tick to Sort the entire list after the objects are added.

Click Finish.

Result   The list of lists is displayed in the editor.

To remove a list from the List of lists to document, right-click a list in the editor and select  Remove in the contextual menu.

For the documentation to be complete, you must be able to integrate elements that do not directly belong to the information system. ARCAD Observer enables you to manage user-defined information.

It is possible to add notes or comments at any level of your documentation. While comments are saved with the documentation project in ARCAD Observer only, notes will appear as parts of the final documentation.

The documentation's customization options

Notes are information that are part of the completed documentation. Notes can be user-defined elements or diagrams calculated in the navigator section of ARCAD Observer.

Important!

Notes can be text, diagrams or ARCAD lists.

The diagrams generated and saved during the analysis can be added to the final documentation through notes.

Follow the subsequent steps to add a note to the documentation.

Step 1   Right-click on a chapter or a section of the document in the table of contents, and select  Add a note in the contextual menu.

The note creation wizard opens.

Step 2   Tick the Has a title option to show the note title in the final documentation. Enter a title for the note in the title field.

Step 3   Select the Note position. Tick the Header button to put the note in the header of the chapter or section, or tick the Footer button.

Step 4   Tick the corresponding button to select a Note type:

  • Text: add text and links.
  • Graph: insert a graph.
  • List: add an ARCAD list.

Click Next > to continue.

Step 5   Define the note according to its type.

  • Enter the text in the text input field.
  • Click the  add image icon and or the  add hyperlink icon to add external resources to the note.
  • In the file selection dialog, select the file you wish to reference. Click Open.
Note

The diagrams use in a documentation are duplicates of existing diagrams, which means that modification of the original diagram will not affect the diagram in the note.

  • Click the Diagram button.
  • Select your diagram in the diagram dialog.
  • [Optional] Select the display Height and Width of the diagram. Click OK.
  • Select a list in the list manager.

Step 6   Click Finish.

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

To edit a note, click on the note in the table of contents and make the necessary modifications in the Parameters section of the documentation editor.

You can add as many notes as you wish. If you have added several notes to a section or a chapter, you can reorder the notes in the section or chapter. In the table of contents ,right-click on the note and select  Move up or  Move down in the contextual menu.

Note

Reordering a note is done within the header or the footer.

To delete a note, right-click on the note in the table of contents and select  Delete.

Comments are intended to create a dialog between the different operators in documentation generation. They are presented in text form and will not be included in the final documentation.

Follow the subsequent steps to add a comment.

Step 1   Right-click on a chapter or a section of the document in the table of contents, and select  Add a comment in the contextual menu.

A comment is added in the section or chapter node.

Step 2   Enter a comment in the Comment section in the documentation view.

Result   You can consult the comments by clicking the comment entries of the table of contents.

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

To edit a comment, click on the comment in the table of contents and make the necessary modifications in the Parameters section of the documentation editor.

To delete a comment, right-click on the comment in the table of contents and select  Delete.

You can preview your documentation in the documentation version editor.

Important!

By default, the documentation preview is displayed in the editor, unless you have changed the default viewer in the Preferences.

Reference

Refer to Documenter preferences.

In the Document tab, click on a chapter or a section of the table of contents to display a preview of the documentation.

Note

This action is similar to generating a part of the documentation and will validate the content and the layout. This can be useful to perform a validation on a sample element rather than on the entire documentation.

Documentation preview

The generation of the documentation does not produce any documents. This is only an update of the ARCAD Database. Generating the documentation is required to export the documentation.

To generate the complete document, right-click on the version in the navigator and select  Generate all in the contextual menu.

It is possible generate the complete document from scratch. In this case, the documentation stored in the ARCAD database will be calculated and saved again. To generate the complete document form scratch, right-click on the version in the navigator and select  Generate all from scratch in the contextual menu.

A progress dialog is display when the documentation generation job is calculating and when the job is finished.

With ARCAD Observer, you can export your documentation for external consultation or publication in different formats. To do this, the export engine will generate a directory whose structure and data can be transferred to an HTTP server.

Important!

ARCAD Observer does not offer site deployment features. This task will belong to the company’s web site management department.

When the documentation is generated, it can be exported. There is three ways to export documentation:

  • export to site,
  • export to file, or
  • export to Confluence.

Export in multiple web-pages is useful to upload files on a remote site.

Note

If you have defined external references in your documentation, ARCAD Observer is able to identify them and make a copy in the export directory.

You can export the documentation to multiple files HTML format.

Step 1   To export the documentation version, right-click on the version in the navigator and select  Export to site in the contextual menu.

Step 2   Click the  Browse icon to select the Export location.

Define the directory in which the site structure will be saved. In the export location dialog, you can navigate to the desired directory, or create a new one if needed.

Step 3   Tick the Include section option to include all the sections to the side navigation of the exported documentation. Otherwise, only chapter entries are included in the navigation.

Step 4   Click Next > to continue.

Step 5   Define the layout of the final documentation.

Header setup Height: select the height, in pixels, of the header section of the final documentation.
Background Color and Font: select the background color of the header and the format (the font, color and size) of the header's text.
Background image Set an image in the background: tick this option if you want to use an image as background instead.
Click the  Browse icon to select a background image from your file system.
Transparent: tick this option to make the background image transparent.
Image style: tick the Mosaic option to repeat the background image across the header or tick the Logo option to use the image as a logo, situated at the top left corner of the header.
Footer setup Title: enter the title displayed in the footer.
Height: select the height, in pixels, of the footer section of the final documentation.
Background Color and Font: select the background color of the footer and the format (the font, color and size) of the footer text.

Step 6    Click Finish.

Result   The documentation is exported to multiple web pages. You can open it in any web browser.

You can export the documentation to a single file HTML format, that contains all of your documentation.

Important!

As pictures cannot be stored in an HTML file, they are stored in a directory. They will be referenced using hypertext links in the export file.

Step 1   To export the document version, right-click on the version in the navigator and select  Export file in the contextual menu.

Step 2   Click the  Browse icon to select the Export location.

Define the directory in which the file will be saved. In the export location dialog, you can navigate to the desired directory, or create a new one if needed.

Step 3   Tick the Include section option to include all the sections to the table of contents of the exported documentation. Otherwise, only chapter entries will be included in the table of contents.

Step 4   Enter a File name. Indicate the name of the HTML file that will contain your documentation.

Step 5    Click Finish.

Result   The documentation is exported. You can open it in any web browser.

You can export the documentation to a defined Confluence space, that contains all of your documentation.

Reference

To set the connection to your Confluence space, set the preferences described in the Confluence documentation upload.

Follow the subsequent steps to export your documentation to Confluence.

Step 1   In the ARCAD Observer navigator, open the desired documentation project.

Step 2   Right-click on the version of the documentation that needs to be exported and click the  Export to Confluence button.

The Export to Confluence wizard opens.

Step 3   In the Export to Confluence wizard, define the space where to export the documentation in the Confluence space key field.

Reference

To retrieve the Confluence space key, go to a designed Confluence space, click on the Space tools button and then on Overview. The key field contains the Space key.

Step 4   In the Export to Confluence wizard, fill the Documentation home page title field.

Important!

This documentation title must be unique in Confluence. Click the Check title in Confluence to make sure the title does not exist already in the Confluence space.
If you export to Confluence with a document title that already exists in the space, an error message is displayed.

Note

If you test the uniqueness of the document title and it already exists, the wizard then displays a Delete Confluence document button, that allows you to delete the existing documentation in Confluence. The deleting process can take a few minutes, depending on the number of pages.
If you wish to keep the existing documentation in Confluence, you can modify the title in the Documentation home page title and test it again.

Result   The documentation is successfully exported and you can access the pages in your Confluence space.

Closing a documentation version consists in declaring all phases of documentation generation to be complete. Once the version is closed, no modification of any kind can be made.

Follow the subsequent steps to close your version.

Step 1   In the ARCAD Observer navigator, open the documentation project.

Step 2   Right-click on the documentation version and select  Close in the contextual menu.

Step 3   Click OK to validate closure or Cancel to cancel the operation.

Result   The documentation version is closed. The closed documentation version is displayed with a lock.

Updating a documentation means recalculating obsolete information. Information can be considered obsolete when:

  • Changes are made on components (cross-reference, calling chain …).
  • New components are added in the repository or a version.
  • Components are deleted in the repository, or a version.

Within an ARCAD version of an application, this information is made available and is used to complete the update operation.

To update a documentation, duplicate the documentation version using the options to recover the component list, the version list and the list of lists; and also the option to recover the documentation contents. Then, generate the documentation.

Reference

Refer toDuplicating a documentation version.

Refer toGenerating documentations.

Warning!

Deleted documentation versions cannot be accessed or recovered

To delete a documentation version, right-click on the item in the application navigator and select  Delete. Click OK to confirm or click Cancel to keep the documentation version in the dialog.