Perils of DITA publishing, part 1: Writing

In which we develop narrative content in a modular architecture.

First in a series of posts describing how the team at Scriptorium used DITA as the foundational technology for our new book, Content Strategy 101.

In late 2011, Alan Pringle and I decided to write a content strategy book focused on technical communication issues. Sometime after deciding on a general concept and an outline, we had to make some important decisions about tools and technologies. Here’s what we knew:

• The writing process would be highly collaborative—I might draft a section and then Alan would add to it or vice versa.
• We expected the content to evolve. In fact, we ended up doing major restructuring three times before we found an organizing scheme for the book that made sense to us.
• We wanted maximum flexibility in delivery. At a minimum, we would have to deliver PDF (for the print edition) and EPUB. Kindle format was also desirable.
• We had some content in blog posts (WordPress) and in DITA files, but at least 70 percent of the content would be written from scratch. An additional 20 percent would require heavy rewriting.

We chose DITA as the source format. Conveniently, we already have infrastructure for publishing DITA content to PDF, EPUB, and Kindle (although we have made a lot of changes over the last few months). In addition to flexibility with output, DITA also gave us the ability to break up the book into lots of small files and then to work on those files simultaneously.

Here are some other stylistic decisions that we made:

• For most of our topics, we used the <concept> topic type. We could have also used the generic <topic>. Information typing was definitely not a strong point for this book.
• We skipped the <shortdesc> element. In print, <shortdesc> content is not rendered. In EPUB or other online deliverables, <shortdesc> content could theoretically become hover text (displayed when you put the cursor over an entry in the table of contents), but we felt that the effort of creating that content was not worthwhile for a narrative book.
• We did not use related links. Most of our links were to external sources, and we ended up using footnote (<fn>) elements for most of them. We developed a standard for external references that would accommodate both print and online deliverables:
  
  

  ....Within 50 years, that number rose to 12 million.
  
  hrc.utexas.edu/educator/modules/gutenberg/books/legacy/ ...

  
  We included a cross-reference (<xref>) in the link with the full target link information, but for print delivery, we also included the URL as text. We later modified the output processing so that the links appear in the PDF (destined for print) without any special formatting (no blue underline) as links are not exactly clickable on paper.
• We had some trouble with special characters, such as em dashes, en dashes, and curly quotes. Eventually, we got in the habit of using the keyboard commands to insert them, and we did a global search and replace (carefully) to find stray characters we missed.

Overall, the writing process went relatively smoothly. Our ability to manage content updates by topic was a huge win.

We are planning a series of posts that describe other aspects of the DITA publishing process, including graphics, indexing, and PDF configuration. Watch this space for more.

What has been your experience writing DITA content? Have you used it for narrative books? What are the biggest advantages and disadvantages?