What are Stylesheets?
For many of those that implement a DITA or structured content framework, stylesheets can be an intimidating piece of the puzzle. But they don’t have to be. Let’s start by talking about what stylesheets are and how they work. Stylesheets format published documents. Stylesheets turn your structured content into delivery formats, such as PDF, HTML, or chatbot content. In DITA, stylesheets are most often embedded in a publishing plugin and processed using the DITA Open Toolkit (DITA OT). Stylesheets can include items such as your branding and logos, headers and footers, and preferred fonts. They can also be much more granular, such as specifying formatting of examples within a task or interface components within software documentation.
Moving from an unstructured writing environment, like Microsoft Word or FrameMaker, to DITA can also mean a significant shift in the way that you not only write content, but publish it. In unstructured environments, styling is often applied to the content as it’s written. For example, you might apply heading labels, bold, italic, and underlining manually to influence the way the final product looks. In a study conducted by Procedure Solutions Management, LLC, they found that in a group of Microsoft Word users, “On average, 30 to 50% of the total document development labor hours were dedicated just to formatting.”1
In DITA, styling is completely divorced from the writing process. Instead of applying styling while you write, you apply semantic “tags” to your content by using DITA elements to identify the type of content. Then, when you publish that content, you use publishing plugins that contain stylesheets to apply your desired styling. For example, if you’re writing software documentation, you might use elements like UI Controls or Window Titles for interface components. Then, your stylesheet applies rules, such as bolding text in UI Control elements or italicizing text in Window Title elements.
Why use stylesheets?
Well, if you’re creating structured content, such as DITA, you really must use stylesheets if you want to apply organization-specific formatting to your published content. But furthermore, there are significant benefits to using stylesheets. First, you can guarantee consistent styling in the published output. You no longer need to rely on authors to consistently apply styling when they’re writing. Six Degrees writes that,
“Communicating with too many voices and with too much variation can compromise brand equity and confuse audiences by expressing multiple personalities and leave messages open to interpretation. Communicating with a universal set of style and formatting conventions is necessary to articulate brand promises and strategic priorities, maintain a reputation of reliability, generate consumer confidence and build a personal relationship with customers.”2
In technical documentation, it’s especially important that formatting is consistent because you’re providing your end users documentation for their immediate use, not for pleasure reading. Inconsistent styling can be a distraction and cause usability issues. Most readers of technical documentation are looking for the specific information they need, not reading the entire user guide. When your readers access information for this purpose, consistent styling can help them find what they need and improve their user experience.
Second, your writers gain efficiency because they can focus on writing instead of styling. If authors use different types of formatting, they can create inconsistencies that must then be corrected. With stylesheets, time-consuming styling work no longer takes up anyone’s time once the initial setup is complete. You can simply use your stylesheets to publish with the push of a button.
Ultimately, the selling point for stylesheets is that you can publish your structured content from a single source to multiple output formats, in any language, and guarantee consistent styling. Furthermore, you can accomplish all this while leveraging the efficiency of your writers.
Regardless of how you approach the development of stylesheets, you’ll need to specify the requirements for the output you’d like to achieve. There are a couple ways to go about this. A good first step is to provide the person developing your stylesheets with a good example of your preferred output (if you have one available). Second, it’s helpful to use a template to gather the remaining requirements. For example, we use a checklist to gather customer requirements. Here’s a small excerpt:
- Document formatting:
- Page size
- Orientation
- Cover/back pages
- Icons (remember any icons that go with individual elements)
- Need to have an adequate resolution or be vector-based
- Need to specify the on-page size
- Number of levels in Table of Contents (TOC)
- Indentation of TOC hierarchy
- How to handle wrapping of long titles
- Leaders between the title and the page number (dot leader or no leader, as examples)
- Text formatting of each TOC hierarchy level
The crux of the stylesheet issue is the initial setup… it’s not simple and the skill set required to do this part of the implementation is highly specialized. The truth is that very few of our customers develop their own stylesheets for this reason. This is why we recommend using a consultant who specializes in creating stylesheets to build them for you. We also have built lots of stylesheets for customers!
Not your cup of tea?
As I mentioned at the start of this article, stylesheets are often the most intimidating aspect of a DITA implementation. This is because many people simply don’t have the technical skills to do this work and those skills are not easily acquired. Learning to write stylesheets and manipulate DITA OT plugins is nothing like learning a new software.
To create your own stylesheets, you generally need two things: experience working with eXtensible Stylesheet Language Transformations (XSLT) and knowledge of the DITA OT. Knowledge and experience in just one of these areas isn’t sufficient. You may have developers in your organization with XSLT knowledge, but the DITA OT has many moving parts and can have a complex organizational structure that you need to understand to get your publishing plugins to work.
If the thought of stylesheets raises your blood pressure, there’s no need to fear! There are some options out there for you.
At Heretto, we have strong relationships with some fantastic partners that specialize in this type of work. We’d be happy to recommend a consultant that you can work with to develop your stylesheets. We also have an in-house Professional Services team that can develop your stylesheets for you. Both of these options present some additional cost, but the good news is that stylesheet development tends to be a one-time cost and the benefits can help justify the ROI.
Resources
- “How much does it cost to format a document?” 2016. 28 September 2016. <http://proceduresolutionsmgmt.com/formatting/>
- “The Importance of Branding and Identity Style Guide” 2014. 3 November 2014. <https://www.six-degrees.com/the-importance-of-a-branding-and-identity-style-guide/>
