Best Practices for Creating Custom Toolkits
The way you set up your custom DITA-OT directly affects the publishing time you experience. Every time you publish with DITA-OT Cloud, the service takes 20-30 seconds to start a secure, temporary container into which it uploads all resources needed to publish content. Once the container starts, the service uploads the toolkit related to the publishing scenario and the content itself. The larger the resources, the longer it takes to upload them into the container.
On a high level, a couple factors can cause longer publishing times with DITA-OT Cloud:
- Content condition and size
If your content contains unresolved preflight issues like broken links, missing content, unresolved content key references (conkeyref), processing it for publishing takes longer. Always resolve all issues flagged in preflight check before publishing your content. See Preflight Check.
If you publish a large deliverable, it is expected to take more time to publish due to its size.
- DITA-OT size
Default DITA Open Toolkits are typically not larger than 30-50 MB. If your toolkit is configured to publish to multiple output types and contains custom resources like fonts or plugins, its size grows quickly which directly affects publishing time. Ensure that you use multiple toolkits, each configured to publish to only one output type like PDF or HTML.
You are in control of these factors. In this section, we focus on best practices for optimizing custom toolkits and mitigating these factors.
The recommendations in this table can help reduce or avoid long publishing times in DITA-OT Cloud. The general rule of thumb is: Keep your toolkits small. Do not add components to a toolkit that are not needed for a specific publishing scenario.
Resource | Recommendation | Avoid | Impact on publishing time |
|---|---|---|---|
Toolkit version | Use DITA-OT versions 3.6.1 to 3.7.4. They contain parameters that help with processing speed. For more information, go to https://www.dita-ot.org/ and review common parameters for a specific toolkit version. Important: DITA-OT Cloud supports toolkit versions 2.5.4 through 3.7.4. | Don't use DITA-OT versions 2.5.4 to 3.6. They lack parameters that help with processing speed. | Minor |
Toolkit size | Keep your toolkits small. The larger a toolkit, the longer publishing time. Toolkits larger than 500 MB don't upload to the CCMS. For comparison, default toolkits are typically not larger than 30-50 MB. | Do not create large toolkits that contain unnecessary resources. | Critical |
Custom toolkits | Create one toolkit for each output type. For example, create one toolkit for PDF output and a separate toolkit for HTML outputs. There is no limit on the number of toolkits you can upload. This is especially important if you use Antenna House or Oxygen WebHelp. | Don't create one toolkit for all output types. Don't create a toolkit that includes both Antenna House formatter and Oxygen WebHelp plugins. | Critical |
Custom plugins | Add only the custom plugins a publishing scenario needs. For example, a toolkit for PDF outputs should only contain custom plugins related to PDF outputs. | Don't add unrelated custom plugins to a toolkit. For example, a toolkit for PDF outputs should not contain custom HTML plugins. | Major |
Custom fonts | Add only the custom fonts a publishing scenario needs. For example, if you use serif fonts for PDF outputs and sans-serif fonts for HTML outputs, only add the relevant font types to each toolkit. | Don't add all custom fonts to all toolkits. | Minor |
Publishing scenarios | Create one publishing scenario for each output type. For example, create one publishing scenario for PDF outputs and another for HTML outputs. Each scenario should point to an output-specific toolkit that contains only output-specific custom plugins and fonts. For example, a publishing scenario for PDF outputs should point to a PDF-specific toolkit that contains only PDF-specific custom plugins and fonts. | Don't create one publishing scenario for multiple output types. | Critical |
Antenna House | Only include Antenna Housein toolkits configured for PDF output generation. | Don't add to toolkits configured for HTML output and other non-PDF outputs. | Major |
A sophisticated publishing configuration typically combines custom plugins and fonts, uses Antenna House, accounts for localization needs, and supports publishing to multiple output types. The more sophisticated your publishing needs, the more likely it is that your toolkit is large. This affects publishing time and we recommend following these guidelines as much as possible.
If you have optimized your toolkits and publishing scenarios and still need more publishing power, consider purchasing more DITA-OT Cloud workers for concurrent publishing. The number of workers you have by default depends on your Heretto CCMS license type. For details, contact your Customer Success Manager.