Adequate Package Documentation

   Exchange Pre-configured Maestro services.  |   Platform Developer |  All versions   This feature is related to v5.1 and higher.

Each package on the Exchange catalog must be adequately documented so that customers can be self-sufficient when installing, configuring and using the package. This article describes the areas where documentation should be applied in your package.

Fluent SDK Document Generation

When using the Fluent SDK in the IDE, documentation is generated based on the assets found in the project source folder and the descriptive content added by the development team.

There are 2 levels of generated documentation produced by the Fluent SDK:

1. Service Level Documentation

In the source folder for each Groovy service you will find a service-help.html file which is generated each time you package or deploy your service based on the annotations in the Groovy script itself and the descriptive content in the service-def.json file. When deployed to Journey Manager this documentation is visible on the Help Doc tab when viewing the service definition.



See ServiceDoc Annotations to learn how to embed documentation in your Groovy script using annotations.

2. Package Level Documentation
   The package documentation generator pulls information from a range sources in the project source folder to produce a comprehensive manifest and guide for users of the package. Much of this information is created based on system generated files but must be augmented with descriptive content by the package developers. When a TPac is deployed to Journey Manager (under System → TPacs) the readme.html document will be accessible via the package listing.
   
   

Documenting Groovy Services

The documentation generator for Groovy services pulls information from the following 2 sources located within the service source folder:

1. The annotated Groovy script - see ServiceDoc Annotations.
   
2. The service-def.json file is inspected to locate any service parameters that have been added and the parameter JSON definitions are used in the generated service-level documentation. Ensure you provide a clear description for each service parameter you add.
   

Example service parameter definition from a service-def.json file

           {
             "name": "Docusign Email Subject",
             "description" : "The email subject to display for Docusign email delivery",
             "type": "String",
             "value": "Docusign $formName",
             "bind": false,
             "required": false,
             "clearOnExport": false,
             "readOnly": false
            }
        

Documenting Maestro Assets

All descriptive content for Maestro assets should be added by the developer via the Maestro UI. Here we list some examples of the descriptive content contained in Maestro assets that is used in the generation of the package-level documentation:

• Shared Component Descriptions - when you publish a custom component to a Maestro library you are able to specify a description of the component.



• Component Properties and Rule Templates - adding properties or rule templates you are also able to add descriptive content.

The following is an example Maestro component documentation generated into the package-level readme:

Package Overview Documentation

In addition to the automatically generated documentation on Groovy services and Maestro assets, package developers can inject free-form overview instructions and guidelines into the package documentation by editing the package.html file located in the project source folder. All content in this file is added at the top of the package readme.html file and any <h2> headings are treated as a navigable menu item, being added to the left hand navigation.

In the package.html file, developers should provide adequate documentation to enable customer to be self-sufficient in their use of the package. This may include sections on:

• The purpose of the package and the use cases it supports
• Compatibility requirements for the package core modules and any 3rd party dependencies
• Licensing information and contact details for obtaining a license
• Installation and usage instructions
• Details around special features supported by the package
• Release notes detailing all relevant historical releases and the main change between releases
• Legal considerations for those intending to use the package

Example Custom Section

           <h2>Embedding the signing ceremony</h2>
           <p>
            	The embedded signing ceremony required minimal configuration, and can simply be placed on the form.
            	The following rules are provided on the form to allow customisation of the signing experience :
            	<ol>
         			<li>
            			<strong>On Complete</strong>
            			<p>Allows the form designer to specify a script to run when the signing ceremony has been completed.</p>
            		</li>
            		<li>
            			<strong>On Failure</strong>
            			<p>Allows the form designer to specify a script to run if the signing ceremony fails (usually due to a signer opting out or declining to sign)</p>
            		</li>
            	</ol>
            <p class="alert alert-warning"><strong>NOTE</strong> : The signing ceremony will begin as soon as the signing ceremony is visible</p>
            <p class="alert alert-danger"><strong>WARNING</strong> : Once the Signing Ceremony has been created it cannot be changed, as changing the contents of the documents would void the signing package.</p>
           </p>
        

Example Custom Section

Example Release Notes

            <h2>Release Notes</h2>
             
            <p><strong>Version 1.2</strong>  <span class="label label-default">Aug 08, 2017</span></p>
            <ul>
            	<li>Error handling, data validation and usage instructions.</li>
             	<li>Keep Manager session alive as long as the embedded DocuSign signing session is active. A ping request from DocuSign is executed against Manager every 5 minutes.
             	</li>
            </ul>
             
            <p><strong>Version 1.1</strong>  <span class="label label-default">Jun 28, 2017</span></p>
            <ul>
             	<li>Added support for Maestro 5.1 language translation features.</li>
            </ul>
             
            <p><strong>Version 1.0</strong>  <span class="label label-default">Feb 23, 2017</span></p>
            <ul>
             	<li>Baseline release.</li>
            </ul>
        

Example Release Notes

Tip

You should occasionally run the package generator and review the content to ensure that there are no gaps or errors in the documentation. You can manually trigger the generator by running the generate-package-docs Ant target in the project build file. The generated readme.html will be generated into the package folder in your project.

See also Working with the Ant Build Files