Best practices for developing templates and generating documents in IBM Engineering Lifecycle Optimization - Publishing (PUB)

You can use these guidelines to create templates and generate documents in IBM Engineering Lifecycle Optimization - Publishing (PUB).

Best practices for creating templates

When you are designing a template, the following practices can help you use your time efficiently and contribute to a successful document generation:

  • Create separate template for different sections such as title and contents. Separate template promotes template reusability across different document specifications and larger templates.
  • Always specify the template element name and a description based on the purpose of the template.
  • Always include the template comment element throughout the stages of the template. Adding comments about the details of each section works as a great resource for future reference.
  • Implement the overall structure of the template by using a top-down approach. Start with the most general elements and then incrementally narrow down to the details.
  • Validate data generation before you start focusing on formatting details. If you spend much time formatting and then discover that your data is not generating correctly, you might have to reformat. See Test the template for details.
  • Polish the details and add more detailed requirements one by one. Leave less important details or difficult ones to implement later. Consider the relevance of requirements that are difficult to realize, similar to a cost-benefit analysis.
  • Use scripts to extract information into a format that Engineering Publishing can efficiently use.
  • When you add data sources or variables to the template, use the following guidelines:
    • Name the data sources and variables according to the standard naming convention.
    • Include a description of the data source and variable usage and behavior.
    • Do not configure the data source every time you need the data source configuration (DSC) element connection details, instead you can inherit the details from the parent data source itself.
    • If you want to assign values to template variables, it is advisable to use the JavaScript element rather than using Assignment property. JavaScript template elements are easier to view and enable quicker editing within Document Studio.
    • Run the template against the data source after each modification and change that you make during template creation.
    • Set the Configuration required property to hidden to hide dynamically configured data sources, which result in displaying only the relevant data sources to the user.
  • When you add a table to the template, use the following guidelines:
    • Iterate on the row level element within the table instead of the iterating on entire table to speed up the table creation and improve the template performance.
    • Use a consistent layout in your table across the templates. For instance, use a common style for the heading row cells.
    • Allow Word or PUB to handle table layout formatting tasks, such as resizing the table and breaking up the text within the table cells or columns, in the template. The result is a proportionate and appealing table with minimal efforts.
  • Add debug statements at different sections of the template by using the default internal variable _sessionLogger. This will help in identifying problematic section of the template, when something goes wrong.
  • You can use the default internal variable _sessionInfo to retrieve the session-related information, such as the template path, configuration context, output path, and so on.
  • Take backups of each version of your template. By using the backups, you can roll back the changes instantly.

Best practices for generating documents

IBM Engineering Lifecycle Optimization - Publishing (PUB) is designed to handle large amounts of data and generate documents, but its capabilities are not unlimited. To avoid document generation errors and failures, use these guidelines while you are generating documents.
  • Document-style reports are considered large for IBM Engineering Lifecycle Optimization - Publishing (PUB) when they consist of a thousand or more pages. To decrease the time that it takes Engineering Publishing to generate large document-style reports, consider using the multipart property in your document specification or changing the contents of your template.
  • Choose only the output type in which you want to generate the document rather than selecting all types. For instance, if you want to generate a Word document, select only the Word output format in your document specification. When you generate a document, each output type requires extra memory. So to reduce memory consumption and improve the performance, select only the output that you need.
  • Schedule the document generation when the CPU is idle to avoid any sort of lag.
  • When a large amount of data is being generated, divide the output into several documents. By using PUB, you can divide the document through filters and template variables. As a result, memory usage is optimized, and you are able to access and generate a part of data according to your requirements. For more information, see: Generating large document-style reports.