The DITA Style Guide (2011), by Tony Self is a collection of best practices for authors on how to apply the DITA standard consistently in terms of naming, writing, mark-up, and structure. 
‘It is just as easy to create poorly marked-up DITA documents as it is to create poorly styled word processing documents’ as Self describes on the role of a style guide.
This is the kind of reference you want to keep handy around your authoring workspace. Its the kind of reference you’ll turn to often, the kind that is useful for orienting new DITA authors, and for experienced authors to find new ways to improve the quality of DITA content authoring.
Getting the book
I ordered my copy of the book in a digital ePub format. I opened it in Adobe Digital Editions, an eBook reader on Windows for the ePub format. Its a fairly simple but slick looking program but seems to lack the robustness of Adobe Acrobat Reader. However, it does a serviceable job as a reader for the ePub version of the book, although on a page or two where text, tables, and page margins overlap, the layout was distorted.
With a total of 635 pages (ePub page counter), the book is also available in a Kindle format for the Amazon eBook reader. If you have an Apple iPad you might be able to read the ePub version of the file on your device. The standard book printed version is also available at discounted rates from Amazon on the Scriptorium website.
Why this book is different
This book is written for authors.
It deals specifically with common authoring questions and language problems that DITA authors face.
For authors, with a background in a HATT tool, authoring in a structured DITA environment for the first time, can be an intimidating experience. It takes time to unlearn old writing practices.
- Why can’t I have more than three levels of sub steps?
- How do I write stem sentences in task topics?
- How do I write short descriptions?
- What is a definition list for, and do I need to use them?
A style guide is useful because it presents a set of guidelines or best practices to accomplish better results in DITA.
Chapter one
‘Chapter 1: Information types and topics’ introduces the the DITA topic types – task, reference and concept topics. Much has been written on the unique DITA structure in STC white papers, journals and trade magazines.
Chapter two
Chapter 2: DITA map files is about the DITAMAP – mapping files used to define the topics, links and sequence in a publication.
A ditamap is quite similar to the TOC file if you are authoring in Flare. In DITA, there is an additional dita map file for book or pdf outputs called a bookmap – a specialization of the DITA map file. I can’t think of a close enough equivalent of a bookmap in Flare since a TOC file in Flare can be used for both online and PDF book outputs. Ultimately a bookmap contains the major structures for a book layout convention such as book meta data, titles, chapters, front matter, back matter and appendix topics.
The book introduces how the dita map file is meant to be used. From the book, I think a dita map is one of the most important components in a dita project. file as the location where you establish topic relationships links, hierarchies and even task prerequisites between topics. This is where I think DITA places a serious reliance on a robust transform engine – to convert and format links into PDF book pages or topics for a CHM help topic with the appropriate see also or navigational links.
Chapter three
“Chapter 3: Syntax and mark up” describes the “how to” of writing for DITA. Tony Self and the editorial team made efforts to keep descriptions of each major DITA element concise, with many helpful examples. It also addresses one of the greatest difficulties I have had with the adjustment to DITA – how to use the appropriate mark up.
If you are new to DITA, DITA can feel restrictive. Concepts, reference and task topics have a slightly different set of available tags depending of where you are in a topic. For example, you may not be able to apply the same tags in a concept topic as you would in a task topic.
For years, I have been programmed to define my own tag classes in the style sheet. In a structured DITA environment, using the right markup for the right topic is more important. This is what the book addresses.There are four kinds of lists in DITA, and Self describes when to use each list. Other elements described include, using phrases, tables, and how to include special characters and dates.
If I really must have something to say, this chapter could probably be improved if both correct and incorrect use of markup or authoring elements were used more consistently.
Chapter four
“Chapter four: Language and punctuation” is about configuring your language and using the right punctuation. Like Chapter three, this chapter is extremely helpful especially on how to think about taking a minimalist approach to stem sentences, glue text and transitional information.
Chapter five to six
Covers graphics, captioning, how to use callouts, web accessibility, and the challenges presented by globalization of rich media. Can you insert multimedia elements in DITA? Its covered in this chapter. Cross-references and how to use them correctly in DITA can be an interesting practice to adapt to.
Chapter seven, eight, and nine
Chapter seven describes the elements of reusability like variables, organizing topics. Chapter eight is about conditioning and filtering content for reuse. Chapter nine describes the strategic processes, content management systems, file folder naming conventions, and review structures to improve the quality of output.
Note: The entire book was actually authored in DITA.
Posted on April 21, 2011
0