A year ago a customer from a Truck Manufacturing Company sat down with me to discuss their technical documentation requirements and what they wanted to be delivering to their customers over the next five years.
They had performed an initial review into various specifications and had come to the conclusion that they should choose either S1000D or DITA. They wanted my opinion on these two specifications, including the differences, benefits and disadvantages to working with each.
As a background both DITA and S1000D are specifications (not standards). The DITA specification v1.0 was formally approved in 2005, with V1.0 of the S1000D specification being first approved in 1989.
Below are some of the items that need to be considered when looking at implementation of either S1000D or DITA. There are a range of similarities between S1000D and DITA along with advantages and disadvantages when considering each:
Similarities between S1000D and DITA
- Reuse of content
- Single Source Publishing, write it once and deliver to multiple outputs
- Structured Authoring software is required
- Content is presented by stylesheet (XSLT for HTML or XSL-FO for PDF)
- Development of stylesheets for customised presentation
- Migration of legacy content
- Validation of content against the schema
- Translation savings for delivery to multiple languages
- Focus for the authors is on writing the content with the correct mark-up, not about how that content will be presented or delivered
Global benefits for both S1000D & DITA
- Schema driven
- Tasks specific for Maintainers and Operators
- Crew Schema manages structure for operators
- Applicability (S1000D) and Audience attributes (DITA) provides the ability to reuse the same content for various models
- CSDB (S1000D) and CMS (DITA) databases are used to manage all content for the project
- S1000D Business Rules are developed to help manage the project, as the project develops the Business Rules are updated to reflect the changes
- DITA uses checklist to determine what features are to be used for the project
- Images and Data Module References are managed by the CSDB/CMS
Additional benefits of S1000D
- Modification of the schemas is not required as authors reference the Business Rules for guidance on authoring
- Procedural Steps allow for 8 levels deep
- CSDB manages all revisions of each file
- Duplicates of files is not allowed in S1000D
- Latest published content is only included in deliveries
Disadvantages of DITA
- Flexibility of the DITA schema allows for elements to be used in multiple locations
- Customization of the schema may be required to ensure writers author content correctly
- DITA Open Toolkit has a pre-defined presentation and if this presentation is not acceptable the stylesheet will need to be modified.
- File and Folder names need to be managed to ensure that the DITA Open Toolkit will operate correctly
- Xrefs, image and topicrefs need to include folder paths. All folder names cannot contain spaces or punctuation
- Delivery could include content that has not been verified
Disadvantages of S1000D
- Data Module Code defines the location within the asset that the content relates to
- Development of the Business Rules can be time consuming up font, although this will save substantial time in authoring and delivery later.
- Stylesheets need to be developed to provide the presentation of the content, although most vendors ship with default S1000D Stylesheet packs.
Even with DITA being classed as a free or low cost solution, there are still costs associated with both solutions and organizations should prepare for budget in the following areas:
- CSDB/CMS – the storing of content should be managed via a smart database, to obtain best results
- Authoring tool – Microsoft Word cannot be used for either of these environments
- Stylesheet development – to customize the presentation of content
- Business Rules (S1000D) – the project should develop Business Rules for each project
- Checklist (DITA) – time needs to be spent looking at the options that are available and determining what elements/attributes are required for the project
The final decision on the solution will need to be made by the organizations management, but they must be able to understand the costs and benefits to these specifications to make an informed decision.
To review a customer success story of S1000D being implemented into a Mining Vehicle Equipment Manufacturing site, refer to the MacLean Engineering case study.