This chapter explains how to use the project documentation functionality included in VoiceObjects and how to export a storyboard.

Creating Project Documentation

The project documentation functionality is used to document the overall structure as well as specific details of your project e.g. to present it to customers, for internal meetings and so on.

You can create a PDF file that either shows the dialog flow similar to its display in the Dialog Designer, or a table overview of all or a selected subset of objects, or both. The PDF document can be created for the entire project version or starting from a particular object. When creating the project documentation for the entire project version, the system loops through all existing Module objects and creates the corresponding documentation. When starting from a particular object the project documentation only shows objects that are referenced within the corresponding subtree of the application.

Creating project documentation always consists of three steps: Selecting the desired documentation format (dialog flow, object overview or both), specifying the corresponding options for the selected format and finally defining the filename and location for storing the generated PDF document.

Prerequisites

In order to work with the created Project Documentation it is required to have Adobe Acrobat Reader 7.0.3 (or higher) including all latest updates installed on your system.

The generated PDF files contain VoiceObjects images by default. A large logo is embedded in the cover page, and a small logo can be found in the header of each subsequent page. You can change these by adjusting a setting in the VoiceObjects Desktop configuration file.

To change the logo, do the following:

1.        Open the Eclipse_Configuration.xml file in the VoiceObjectsDesktop\plugins\com.voiceobjects.eclipseDesktop_9.0.0\config folder of your VoiceObjects installation.

2.        Change the <documentation> element so that <smallLogo> and <mainLogo> point to valid .gif files holding the desired logo. Note that due to space restrictions the cover page logo should have a maximum size of 260 x 70 pixels, the smaller logo 16 x 16 pixels.

<documentation>
   <smallLogo>
       http://localhost:8070/VoiceObjects/images/myLogo.gif
   </smallLogo>

   <mainLogo>
       http://localhost:8070/VoiceObjects/images/myLogo.gif
   </mainLogo>
</documentation>

3.        Restart VoiceObjects Desktop for Eclipse.

i8Note: In some environments, project documentation cannot be created if you leave these settings at default. If this is the case, point the Desktop to images\printing\VoiceObjects.gif for the main logo, and images\printing\VoiceObjectsSign.gif for the small logo under the used web context (e.g. http://localhost:8070/VoiceObjects/).

Unicode

If you use Unicode (UTF-8) characters in your project, such as object names, alternative texts in Audio objects, etc. you need to configure a font capable of displaying those characters. To configure a suitable font, do the following:

1.        Open the Eclipse_Configuration.xml file in the VoiceObjectsDesktop\plugins\com.voiceobjects.eclipseDesktop_9.0.0\config folder of your VoiceObjects installation.

2.        Change the <documentation> element so that <unicodeFont> points to the location of a true type font supporting Unicode. This font should be located on the machine that runs VoiceObjects Desktop for Eclipse.

<documentation>
   ...

   <unicodeFont>
       C:\VoiceObjects\Platform\WEB-INF\config\ARIALUNI.TTF
   </unicodeFont>

</documentation>

3.        Restart VoiceObjects Desktop for Eclipse.

@8  Tip: If you do not have a Unicode font available, you can download one from the Internet. The following table shows three examples; note the respective license agreements.

Font	Download URL
Adobe Song	http://www.adobe.com/products/acrobat/acrrasianfontpack.html
Arial Unicode	http://www.ascendercorp.com/msfonts/arial_unicode.html
CJK UniFonts	http://www.freedesktop.org/wiki/Software/CJKUnifonts/Download/

Select documentation format

In the first step, select the desired format for your project documentation.

To create project documentation for a particular object, do the following:

1.        In the Object Browser, the Dialog Designer or the Search Result, select the object you want to use as the start object for the documentation and right-click it.

2.        From the context menu, select Tools and then Project Documentation.

To create project documentation for the entire project version, do the following:

·          On the menu bar, open the VoiceObjects menu and select Project Documentation.

In both cases the Project Documentation window opens up.

 

1.        In the Project Documentation window, select a documentation format (either dialog flow, object overview, or both) and click Next.

2.        Depending on your selection a second dialog comes up to specify further options.

Specify options for dialog flow

In the Dialog Flow window you specify the formatting options for the dialog flow documentation.

 

1.        In the Paper format field, select a paper format for the PDF document.

2.        If you choose to include a cover page by selecting the check box Include cover page you may add an optional comment in the Comment field.

3.        Select the object details to be included in the dialog similar to the display options in the Dialog Designer. For details see Display Options in Chapter 5 – Dialog Designer.

4.        Click Next to define a filename and a location.

Specify options for object overview

In the Object Overview window you specify the formatting options for the object overview documentation and select the object types to be included.

 

1.        In the Paper format field, select a paper format for the documentation.

2.        If you choose to include a cover page by selecting the check box Include cover page you may add an optional comment in the Comment field.

3.        Select the object details to be included in the object overview.
i8Note: All objects that are only referenced in one of the object details not being selected (e.g. hyperlinks that are only referenced in event handling) are left out when creating the object overview. To include them select the appropriate object details. An exception to this rule is that the reference library will always be shown, regardless of the setting for pre-/postprocessing.

4.        Specify the object types to be included in the object overview by clicking the Choose button  right from the Object Types field. In the Object Types Selection dialog which comes up select or clear the check boxes accordingly. By default, all object types except of Audio are selected.

5.        Click Next to define a filename and a location.

Combine dialog flow and object overview

If you select to create both a dialog flow as well as an object overview a corresponding window will open up that combines the options to be specified.

 

Specify the options as described above (Specify options for dialog flow and Specify options for object overview).

Note that if you select Show pre-/postprocessing in dialog flow but leave Show pre-postprocessing in overview clear, the overview tables for the objects appearing in the pre- or postprocessing of an object are created nevertheless, since they are shown in the dialog flow.

Define filename and location

Finally, a filename and location have to be specified for storing the created PDF document in the workspace of Desktop for Eclipse.

 

1.        Select a location in the workspace of Desktop for Eclipse and optionally change the filename. By default the name of the project version or the object is offered as filename followed by the file extension .pdf.

2.        Click Finish to start creating the project documentation.

A PDF document will be generated displaying cover page, dialog flow and/or object overview according to your selection. If the project documentation has been created for the entire project version the objects will show up in the overview in an alphabetical order. If it has been created for a specific start object they will appear in a logical order, representing their occurrence in the dialog flow.

The PDF document will be added to the workspace of Desktop for Eclipse, which is shown in the Navigator initially displayed as a tab in the upper left corner of Desktop for Eclipse (see Chapter 2 – Desktop for Eclipse Elements for details).

In order to view the created project documentation Eclipse has to be configured accordingly by doing the following:

1.       From the menu bar, open the Window menu and select Preferences.

2.       Expand the General section, then the Editor section below and click File Associations.

 

3.       Check if the file types list already contains an entry for PDF documents.
If it does, check if the section Associated editors (displayed at the bottom) contains the correct program assignment for this file extension.
Otherwise click Add, and in the New File Type window that comes up enter *.pdf as a new file extension and click OK.

4.       To associate an editor with the *.pdf file extension, click Add next to the Associated editors area.

5.       In the Editor Selection window, click External Programs, select Adobe Acrobat 7.0 Document (or a similar entry) from the editor selection list, and click OK.

6.       In the Preferences window, click OK to save your settings.

Project Documentation Content

Cover page

The cover page lists general information about the name, the short description, the creation date and the owner for both project and project version.

 

Dialog flow

The dialog flow shows the objects in the same way as they appear in the Dialog Designer of VoiceObjects Desktop.

 

If the project documentation is created for the entire project it contains the dialog flow for all Module objects of the application. Otherwise the dialog flow starts with the selected object and shows only a subtree of the application.

If the object overviews are generated together with the dialog flow, every object in the flow is linked with its definition table. By clicking an object's name, you arrive at its definition. Use the PDF viewer's backward button to jump back to the flow.

Object overview

The object overview lists all object definitions that are referenced either within the subtree the project documentation has been created for, or within any Module object in case the project documentation has been created for the entire project.

 

As a general guideline, the object overview only shows the fields that are filled by the user, drop-down fields, check boxes, and fields within Options sections. All other fields, especially empty text fields, are left out. In the example above, the Welcome Message section of the Module object Check existing claim is left out, since it is not defined in the object. In both Module objects shown, the Goodbye Message is left out.
The dark-grey header of each object shows the name, short description and comment (if available).

Within the object overview you will find hyperlinks to jump from an object to its child objects. Available hyperlinks are indicated by blue object names.

i8Note: Unused objects are not listed in the object overview, as they are not referenced in any object.

Statistics page

The statistics page is automatically generated when an object overview is created. It is not included if only a dialog flow is created.

 

It lists all object types present in the document and displays the total number of objects per type. The statistics page also serves as a table of contents. By clicking an object type you arrive at the corresponding section in the PDF file. Note that a hyperlink for an object type is only available if at least one object of this type exists in your application.

i8Note: The statistics page only shows objects that occur in the exported document. It does not give numbers on all objects of your application.

Creating Storyboard Export

A storyboard contains a list of all prompts of your application as a Microsoft Excel document. Storyboards can be created for an entire project version or only a subset thereof (through a start object).

To create a storyboard export for a particular object, do the following:

1.        In the Object Browser, the Dialog Designer or the Search Result, select the object you want to use as the start object for your storyboard export and right-click it.

2.        From the context menu, select Tools and then Storyboard Export.

To create a storyboard export for the entire project version, do the following:

·          On the menu bar, open the VoiceObjects menu and select Storyboard Export.

In both cases the Storyboard Export window opens up.

 

1.        If desired, enter a comment, which will be placed into the Excel sheet.

2.        Click Next to define a filename and a location.

The filename and location have to be specified for storing the created Microsoft Excel document in the workspace of Desktop for Eclipse.

 

3.        Select a location in the workspace of Desktop for Eclipse and optionally change the filename. By default the name of the project version or the object is offered as filename followed by the file extension .xls.

4.        Click Finish to finish start the storyboard export.

A Microsoft Excel document will be generated displaying an overview page, all prompts of the project version or the object and some statistic information about number of prompts and words. The document will be added to the workspace of Desktop for Eclipse, which is shown in the Navigator initially displayed as a tab in the upper left corner of Desktop for Eclipse (see Chapter 2 – Desktop for Eclipse Elements for details).

In order to view the created storyboard export Eclipse has to be configured accordingly. For details see Define filename and location above using .xls as file extension and Microsoft Excel 2000 or later as external program.

i8Note: In order to work with the created Storyboard Export it is required to have Microsoft Excel 2000 or later including VBA (Visual Basic for Applications) installed on your system.

i8Note: Depending on the size of your application and the number of prompts, the process of creating the storyboard, together with loading Microsoft Excel, may take up to several minutes.

For further information on how to modify the view, edit and print the storyboard export file with the Storyboard Manager see the Storyboard Manager Guide.