Writing for the formatted output is one of the key differences between traditional technical writing and structured writing methods. (video available on YouTube)
In structured writing practise, we focus on the correct and schema conformant building blocks of our documents. We remove the emphasis from style, layout and look and feel and turn it to structure.
We do this to support data exchange and allow software and technology to control formatting, layout and look and feel. The author is no longer concerned with these traditional writing elements and must leave these traditional mindsets behind.
The author must still know the critical components of a structured document. For example, the author must understand the differences between a title, paragraph, emphasis & types, different lists, and I could go on. In the mind’s eye, the author knows using different structure types to identify content will result in software-controlled presentation.
This method is the core difference between traditional technical writing and the new world of structured content creation.
Why am I writing this blog? Recently I was involved in a call with a small team of ‘XML types’ who know and understand the critical nature of focusing on good structure.
Our task is to take a traditionally produced technical document and convert it to S1000D-based XML. A job that may seem easy on the surface but has thrown up a few technical challenges.
One of these technical challenges is trying to match what the user is familiar with within the old formatted version of the document and present it the same way but from the XML source material.
As the structured content authors, we have no longer control over the formatted output, and we are very much at the mercy of software and printing stylesheets.
When we encountered a situation in the newly printed document, some white space was missing between two document pieces of text. I reverted to my traditional author mindset and said, “just drop in an empty paragraph that’ll fix it”.
To be met with someone shouting “TAG ABUSE”, which made me laugh. But actually, she was right. This empty paragraph is an abuse of the structured writing processes. Would it have achieved the desired results? Yes, but you need to understand the consequences of doing this.
Remember that writing for structured content requires leaving the formatting and presentation to stylesheets via the publishing software. The change has to be made at the stylesheet level and not by the author randomly inserting empty elements to cater for what is missing from the stylesheets.
The consequences are not always apparent to the author. An empty paragraph may seem benign initially, but the implications may remain undetected for some time.
Ultimately the content we are converting will likely end up in IETP form. We must be conscious of how the IETP specific presentation rules will handle any particular instances of ‘tag abuse’ elements. Empty elements can lead to dead space on the screen, confusing the user at best or missing skipping information at worst.
Another good example is in the future deciding to publish the content via a different tool-set with a newer set of stylesheets which may know how to handle the specific formatting requirement. We now have an empty paragraph element that is likely to result in undesired whitespace and gaps in the document flow. Worst case scenario is it could have multiple effects on pagination through the entire technical manual.
Another consequence of inserting empty elements is one of best practice and acceptance. This blog tells us it is best practice to separate the two aspects of a document, valid structure and stylesheets for formatting. Many projects will look for empty elements in their checking tools resulting in rejection of documents that are ‘tag abusing’ their content.
The moral of the story, leave your traditional technical authoring hat on the side when discussing formatted output with purists. Although we did laugh about it at the time, the consequences are not clear to many if we ‘tag abuse’ our content.