December 2015
By Alan Pringle

Image: tiero/istockphoto.com

Alan Pringle is director of operations at Scriptorium Publishing. He helps clients solve problems with the development and distribution of content. His responsibilities include content strategy analysis, automating production and localization tasks (often with XML-based workflows), and managing schedules and budgets for complex consulting projects.


asp[at]scriptorium.com

www.scriptorium.com


 


 

Balancing standardization against the need for creativity

Structured authoring doesn’t have to be the adversary of creative writing. Three case studies reveal how companies can balance standardization and creativity for optimal documentation.

It is a common stereotype that structured authoring is rigid, unbending, and free of creativity. In my experience, the opposite is true. Creativity is necessary to develop structured workflows, and – if developed with the specific requirements in mind – these workflows enable creative solutions. Business requirements often demand flexibility in how content is developed and distributed.

Three short case studies based on Scriptorium Publishing's collaborations with clients illustrate how companies can balance creativity and standardization. The case studies are:

  • Designers communicating layout specifications to programmers for automated outputs
  • Flexible layouts for well-designed print publications
  • Evaluating efforts to customize procedures

Designers communicating layout specifications to programmers for automated outputs

Desktop publishing (DTP) software offers template designers a visual interface for developing the formatting of print and PDF output. The interface shows what the page will look like: the page size, the font for each paragraph, the spacing between paragraphs, and so on.

This visual aspect of template development is missing in structured workflows that generate automated outputs. Instead, programmers use a text or XML editor to develop stylesheet code that defines formatting. So, how can stylesheet programmers and DTP template designers collaborate most efficiently to identify formatting specifications for automated output?

Extensible Stylesheet Language-Formatting Objects (XSL-FO) is a common solution for creating PDF output from XML content (see Figure 1).  

Figure 1: Typical XML-to-PDF process

 

Coding in the XSL-FO stylesheets controls the formatting of the PDF output. The following sample code defines first-level headings:

 

<xsl:variable name="level-1-family">SansBold</xsl:variable>

<xsl:variable name="level-1-size">14pt</xsl:variable>

<xsl:variable name="level-1-line-height">15pt</xsl:variable>

<xsl:variable name="level-1-weight">normal</xsl:variable>

<xsl:variable name="level-1-style">normal</xsl:variable>

<xsl:variable name="level-1-indent">0pt</xsl:variable>

<xsl:variable name="level-1-color">#000000</xsl:variable>

<xsl:variable name="level-1-space-before">42pt</xsl:variable>

<xsl:variable name="level-1-space-after">4pt</xsl:variable>

In their early efforts to gather formatting information, Scriptorium's stylesheet programmers extracted specifications from the paragraph styles, table styles, and so on, in the existing DTP templates. The programmers also received a list of changes from the template designers. Often, the designers made requests such as:

  • "Make the chapter heading a little bigger."
  • "Change the heading color to the new corporate blue."

These requests were perfectly reasonable, but programmatic formatting requires specific numbers. How many points is “a little bigger”? What is the Pantone color code for the corporate blue?

To improve communication between template designers and stylesheet programmers, a Scriptorium stylesheet programmer developed a process that relies on…stylesheets!

First, the programmer added detailed code comments to the stylesheets. For example, for the page size settings, the comment reads:

 

Physical page dimensions. US Letter is 8.5 in x 11 in; A4 is 8.3 in × 11.7 in. Dimensions that accommodate both paper sizes are 8.3 in x 11.0 in.

He then developed another stylesheet-based process that extracts the code comments and creates a Microsoft Word file. The Word file explains each setting and includes the default value. The template designer reviews the settings, modifies the values as necessary, and returns the revised Word file to the programmer (see Figure 2).

Figure 2: Word file excerpt with page size information

 

Using the Word document to collect values greatly streamlines the development process. Programmers receive specific measurements they can add to the stylesheets. Also, the detailed code comments serve as a reference to those who later maintain the stylesheets.

Flexible layouts for well-designed print publications

Automated PDF formatting works well for technical communication. But what about highly-designed content for printed books? How can companies enable flexibility in print/PDF layouts generated from structured content?

Flexibility in PDF output was a requirement for a company's printed study guides. Production specialists, who designed layouts in Adobe InDesign, refined layouts by adjusting the positioning of images, how text breaks across pages, and so on. The designers ensured that the visual flow of content helps readers comprehend the information.

In its transition to structured authoring, the company needed to preserve the high-quality layouts. Automated PDF formatting was not good enough because of the need for precise control over pagination, line breaks, and so on.

Scriptorium programmers developed stylesheets that transform the source XML content into an InDesign-compatible XML file.

Here is a sample of the source XML content:

 

<p>When developing a test bed, it is important to ensure that you cover <b>all</b> basic cases for your requirements.</p>

The transformed XML includes references to styles in the InDesign template, as shown in the following sample:

 

<ParagraphStyleRange AppliedParagraphStyle="ParagraphStyle/body">

         <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/$ID/[No character style]">

            <Content>When developing a test bed, it is important to ensure that you cover </Content>

         </CharacterStyleRange>

         <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/bold">

            <Content>all </Content>

         </CharacterStyleRange>

         <CharacterStyleRange AppliedCharacterStyle="CharacterStyle/$ID/[No character style]">

            <Content>basic cases for your requirements.</Content>

         </CharacterStyleRange>

</ParagraphStyleRange>

When a production specialist places the XML file into the InDesign template, the correct paragraph and character styles, table designs, and other formatting are applied automatically.

Production specialists adjust pagination and image placement in the InDesign content before creating a final PDF file sent for printing. With this new workflow, the publisher maintained the high-quality formatting but significantly reduced the time required for production.

Evaluating efforts to customize procedures

Balancing the standardization of structured content against creative requirements is not just about formatting. When companies choose an XML standard, such as DITA or DocBook, they must evaluate whether to use the default structure or modify it to better fit requirements. The discussion about such changes is a creative process itself. When should a company change default structures?

A company implemented DITA to improve the control over conditional content, support responsive designs for phones and tablets, and manage increasing localization requirements. Content was previously developed with desktop publishing software and distributed in print and PDF. Guides contained procedures with more than 100 steps, which included substeps and sub-substeps.

By default, the DITA standard does not permit sub-substeps in the task structure. The content creators requested the addition of a sub-substep element.

Scriptorium's information architects suggested evaluating the efforts required to either modify or maintain the default structure.

Modifying the default structure would entail the following work:

  • Developing and testing the structure customization
  • Implementing the change in authoring tools, the component content management system, and stylesheets for each type of output (PDF, HTML, Help systems, etc.)
  • Distributing the customization to localization vendors and ensuring their tool chains support the change
  • Training new writers familiar with the default structure on the customized structure

Preserving the default DITA structure for the procedures would require the following effort:

  • Rethinking the structure of procedures so that they did not include sub-substeps
  • Rewriting many procedures to follow the new methodology, which would break up lengthy procedures into smaller related procedures

The content creators were immediately resistant to the idea of rewriting content to match the default structure. They argued that the effort would be too significant due to the large number of procedures. The writers' bias against the new approach was likely increased by the perception that rewriting was an implicit admission that the current procedures were poorly structured.  

The information architects acknowledged that rewriting the procedures would require great short-term effort. However, they believed that the overall benefits of maintaining the standard outweighed the rewriting effort. There would be no costs for implementing and maintaining structural changes for the company or for its localization vendors. New writers with DITA expertise would not need training on custom elements.

More importantly, adhering to the standard offered compelling long-term benefits. The information architects rewrote some procedural content in the default structure. The samples demonstrated how shorter procedures increased opportunities for content reuse, which would reduce writing time and improve consistency. Also, the information architects believed it was essential to consider users reading content on the small screens of phones and tablets. Phone and tablet owners would more easily comprehend shorter procedures.

Ultimately, the content creators and information architects were not able to agree on an approach. The structural changes were not implemented in the pilot project to stay within the project's budget. However, after the pilot was completed, the information development group hired its own full-time information architect and intended to reevaluate the customization with that resource in place. (Not every consulting engagement has a happy, tidy ending, unfortunately.)

Conclusion

Implementing structured authoring does not mean the end of creativity in how companies develop and distribute content. These case studies demonstrate that

  • creative use of technology can streamline communication about design elements;
  • it is possible to reap the benefits of structured source content while preserving flexibility in the formatting of output;
  • considering structural changes is a creative, deliberative process that evaluates both short- and long-term costs. Stakeholder biases affect decisions and increase change resistance.