The role of a style guide

A style guide provides advice on the optimal use of approaches, procedures and processes. A DITA style guide focusses on best practice application of the DITA standard.

The primary purpose of a style guide is to promote consistency. Style guides also aim to codify best practice. What the term best practice actually means is not universally understood or agreed. Understanding what constitutes best practice in DITA is made more challenging by the difficulty in finding agreed practices in this field, let alone best practice. Something as simple as whether paragraphs should exist within list items is not clear-cut.

A style manual or style guide is a set of standards governing the design and writing of documents, and usually takes the form of a printed manual. Publishing organisations, standards bodies, government agencies and publication departments within an organisation are the typical originators of style manuals. Technical publication style manuals used by technical communicators, such as the AGPS Manual of Style and The Chicago Manual of Style, devote a number of chapters to the publishing process, which, in the DITA model, is removed from the technical communicator's domain. Conversely, very little space is devoted to the semantic identification of content elements, something that is core in DITA. The major purpose of a style manual is to promote consistency, and one of the difficulties of DITA adoption is working without a style guide appropriate to the DITA paradigm.

It is just as easy to lazily create poorly marked-up DITA documents as it is to create poorly styled word processing documents. To maximise the opportunities of DITA, it is important that the semantic elements are applied consistently across a publications department, and indeed across the DITA authoring community. The DITA Style Guide is intended to serve as an authoritative reference that defines a best practice conventions for mark-up, writing style, naming, and structure.