When we developed our Technical Writing Skills training course, we created the course materials using the Darwin Information Typing Architecture (DITA), to test its usefulness for small content production projects. DITA is an open XML standard for creating, organising, and publishing topic-based information.
The content team who developed the course material acted as ‘customers’. They drew up requirements for the course, and set milestones and deadlines. The design team (of which I was part) assessed those requirements and found solutions within the parameters set by both the DITA schema and the capabilities of our chosen tool.
In this post, we outline three main challenges faced and overcome by the design team during this process.
About the Project
The content team wanted to publish three types of output:
- Participant handbook
- Presenter handbook
- Presentation slides
Initially, we thought about developing a profile for each output, but eventually decided to create three separate stylesheets. In this way, two stylesheet developers could work independently on their stylesheets.
As DITA 1.3 had not been released, we used the DITA 1.2 standard. We used PTC Arbortext Editor with Styler to develop the course structure and its stylesheets. After using DITA on several client projects in TWi, we were aware of its advantages and disadvantages, and we believed it was a powerful framework for documentation. DITA allowed us to modularize the content, produce it only once, and deliver it in multiple formats.
To create the files, we used a customized DITA Learning and Training document category. The overall course structure is outlined in Figure 1. On the bookmap level, we have a number of chapters, each linking to a different learning group map (module). Learning group maps further reference learning object maps (lessons) that finally reference learning content files. This structure allowed us to freely move the course elements and publish the documents at all levels.
Challenge 1: Creating an Irregular Layout
For the participant handbook, we wanted to limit the text and focus on providing helpful information using the graphics and tips included in the DITA files. We also added dedicated space for participant notes, as shown in Figure 2.
The challenge here was that the order of the DITA files (and consequently, the order of the course content) was specified in the main bookmap. So, in our example, the main title, image, subtitle, short description, and tips would appear one by one in sequence because this was the main content flow of the bookmap. We had to override the content flow specified by the main bookmap; the lines for participant notes were intended to break that flow apart.
The design team chose to use page regions to make this work. Figure 3 shows the region for participant notes in the middle of the page. The tool allowed us to position the participant note lines in the foreground and the main content in the background. This meant that the lines appeared on top of the main content text and could be moved around. Additionally, the lines were generated automatically and triggered by a specified DITA tag.
Adding the participant notes region in this way revealed another challenge. Most of our DITA files had a Tips element, which might have been covered by the participant notes. To overcome this, we manually specified a space before the Tips element to prevent it being hidden behind the newly generated lines. This space had to fit the lines that would be auto-generated at publication.
Challenge 2: Developing a Custom Table of Contents
For the presentation slides, we wanted a table of contents that repeated through the course, highlighting the active lesson at any time (Figure 4). However, the tool’s inbuilt table of contents functionality did not allow this type of highlighting.
To meet the requirement, the stylesheet needed to do the following:
- Determine the number of lessons in a module.
- Create a list of the lesson titles.
- Identify the current lesson.
- Highlight that lesson title.
We created a set of conditions using XML Path Language (XPath) expressions. These helped us find exact nodes that could later be styled in a given context. In our case, the XPath expressions in the conditions counted the number of lessons in a module and captured their titles. To identify the current lesson, we created another set of conditions nested under each of the previous conditions. In these nested conditions, we used another set of XPath expressions to count the number of lessons that occurred before the current location in the structure. For example, if the count was 0, we knew the current lesson was the first one. Finally, for each nested condition, we applied a separate style to the current lesson title (in this case, the pink highlight).
Figure 5 shows the full set of nested conditions. The green highlights on the nodes indicate the contexts and conditions that are currently active. Reading from the bottom, we can see that the active condition selects the third lesson in a module that contains three lessons. This is the condition that selects the pink lesson title in Figure 4.
Challenge 3: Generating Graphic Slides with Text Overlay
For the slides, the content team also wanted to overlay text on top of photographs. Since we planned to single-source all content from the DITA files, we did not want to create the slides using additional software. To present a full-screen graphic in the background and overlay text on the graphic, we defined a new page set for the layout. We also profiled the Fig element in the editor to trigger the new page set for each slide.
We created a specific region on the page that was part of the main content flow, and just big enough for a graphic. Because the graphic filled the region, the following text was pushed into the next page region (also part of the main content flow area), which sat on top of the graphic. This solution worked because we had a specific format: we knew the graphic would be the first element on the page, we knew how big the graphic would be, and we knew how much text might be on the slide. Figure 6 shows the outcome.
For other documentation teams thinking about design tasks in a DITA project, we’d make the following recommendations:
- If you have a lot of content, a robust file structure is a must. The more granular the structure, the better, as it allows the reuse and reorganisation of content in multiple ways. Allow enough time during planning to drill down to the lowest possible level of granularity before proceeding with content generation.
- Select a powerful, flexible XML tool. The tool should offer functionality such as file nesting support and allow you to design stylesheets for multiple outputs.
- Assign people from your documentation team who are not afraid to try new things. During the stylesheet design, there will inevitably be a period of trial and error before achieving your desired outputs. Team members may need to acquire additional skills (for example, learning XPath expressions) to implement more complicated requirements.
By the end of this project, we had designed a course structure and stylesheets that were easy for the content team to both navigate and use, and which produced the expected outputs and visuals. These challenges (and others) were all met due to the flexibility of the DITA schema, the quality of the tools used, and our team’s willingness to find solutions to even the most complex requirements.
HAVE SOMETHING TO SAY?
If you’d like to share your thoughts or know more about this topic, complete our feedback form. We look forward to hearing from you!