When discussions turn to S1000D, many people find that the terminology and requirements to be harder than they expected. In my opinion, many vendors appear to take pleasure in trying to make it sound more complex than it really should be!
So what do you need to understand when moving into S1000D and authoring content?
Templates – Many people already have templates that they use to author their content, S1000D is no different. Instead of being called a template, you use either a DTD or Schema. In authoring tools such as Microsoft Word, you have a template that is based on styles that you will apply to your content. S1000D has the same however the Schema dictates how your structure will appear in your document. It’s simply a matter of changing your thinking. Instead of selecting a style as you would in Microsoft Word, you select an appropriate element or attribute. Once selected you continue to work or author as you normally would.
Presentation – In Microsoft Word or Adobe FrameMaker you enter your content via an interface which provides you with a friendly presentation of this content. In S1000D we have a similar function so that you can see how the content is to be presented. The only consideration that needs to be applied to this is that your selected S1000D authoring tool may present the content so that it appears as per the S1000D specification, not necessarily your final style or presentation delivery.
As authors, you also need to understand what is the difference between the content that has been authored and why the content may not be displayed as it would to the end user. Many people find that this can be an issue, as they want the comfort factor of seeing the information displayed in the final delivery while they are authoring. With S1000D the focus is purposely taken away from the end delivery style or presentation, with focus on authoring the content. The presentation of the content is controlled by the stylesheet that will be used when generating the IETP for the end user. Understanding the need to focus on content, not presentation is one of the biggest changes that authors must get used to early.
Cross References – A major component of authoring, is referencing to information that is contained within the document that you are working on or to another document. In the traditional authoring environments you need to insert these cross references and make sure that they work correctly. In S1000D these are broken up into internal references, references to Data Modules and references to Technical Publications. Each of these have their own specific mark-up requirements however the end result is the same as a cross reference in the traditional publications.
For authoring S1000D you really want to have a tool that will provide you with guidance or automate adding these cross references, and as long as the mark-up is correct, the output in the IETP will be correct. This means that many hours of work can be saved as this content will always work for the end user so long as the authors have followed the rules that are required to enter the cross references into their content. These references are also automatically updated whenever the IETP is created whereas in traditional authoring environments you may have to manually update these to make sure that all content is correctly linked.
Graphics – Images are used extensively in technical documentation. In traditional environments such as Microsoft Word, these graphics are directly embedded into your document and therefore if the graphic is to be updated, you need to locate where it is in the document, delete and then insert the new graphic. With S1000D the graphic is referenced, therefore if the graphic is updated the files that contain the reference to it will also be automatically updated. To assist with this process the CSDB provides you with the ability to view the associations. A good CSDB will also allow you to look-up “where images are used” in one or more data module files.
Multiple content – When using more robust unstructured authoring tools such as Adobe FrameMaker there are features such as Conditional Text which allows you to have multiple variants of information contained in the one document. You have the ability to apply a filter to the content when generating your output and this allows for the content that does not comply with your filter choice to be excluded from your output. This function is also available in S1000D and is called Applicability. There are very specific methods of how this needs to be applied to the content. Once the content has been written and delivered as an IETP you can either include all content and allow the end user to filter, or you can pre-filter the content ready for delivery. The end user can then only see the information that relates to their required task. From an author’s point of view they need to be more aware of what is going on in the content when authoring content with applicability.
Variables – In many authoring environments you can have variables that you can call upon to provide easier ways to enter common or duplicate information once. These variables are available in S1000D but are called Common Information Repositories (CIR). These are files that act like a mini-databases, and can contain information such as Special Tools, Consumables, Spare Parts and Zones. By using these CIR’s you have that ability to reference this common information in your files and if any of the information is updated, this information will be automatically updated in your files without you needing to re-author the content. You only need to update the mini-database files and this then filters through to all of the files that contains CIR references. This is a great time saver for authors, creates consistency in common written content and reduces data entry errors.
Management – Once content has been created, you need a way to understand what content relates to other content. In some traditional environments such as Microsoft Word, this is very difficult, whereas in products such as Adobe FrameMaker you can build a book and use tools such as the Cross-Referenced Pod to manage referenced information such as images and external files. This type of reference and file management is also possible in S1000D, but rather being at a book level, it is at a project level. A good CSDB will normally give you the ability to be able to view all referenced information and understanding the relationships between all content in the CSDB, giving oversite of the entire data delivery for the project.
As you can see, there are many similarities between the process and terminology used in traditional and S1000D environments. The biggest aspect is to make sure that you have appropriate tools to guide and automate the new authoring environment. In addition to the new tools, management need to ensure that the authors are correctly trained to understand their new structured authoring environment which will ensure compliance and achieve a successful S1000D deliverable.
Reeta Nye
Senior Consultant
