A Style Guide for Authoring Documents using DITA An Exegesis submitted for the fulfillment of the requirements for the degree of Doctor of Philosophy 2011 Anthony Self PhD Research Project - Anthony Self | Contents Table of Contents Abstract.............................................................................................6 Document Conventions...................................................................7 Student Declaration..........................................................................9 Chapter 1: Introduction to the Exegesis.......................10 The nature of the Exegesis..........................................................................12 What are style guides?................................................................................12 The need for a DITA style guide........................................................13 Types of style guides.........................................................................14 Is style manual the correct term?......................................................14 Example of the challenges................................................................15 Audit trail of rationale behind rules...............................................................17 Whether to include rationale in The DITA Style Guide......................19 Chapter 2: Literature Review.........................................20 What style guides cover...............................................................................22 Content and form in style guides.......................................................23 Separation of content and form in four style guides..........................24 Style guides.................................................................................................25 Conventional style guides.................................................................26 Writing guides...................................................................................39 Web style guides...............................................................................41 References - Literature Review....................................................................51 Chapter 3: Research Approach......................................54 PhD by Artefact and Exegesis.....................................................................55 Summary of approach to source materials and reference works.................55 Action Research...........................................................................................56 Development of DITA documents as part of Action Research..........57 Analysis of Yahoo! DITA Users Group...............................................58 Work with OASIS Technical Committees...........................................63 History of the Artefact and candidature.......................................................63 Chapter 4: Project Detailed Analysis and Reflection...66 Scope and structure.....................................................................................67 Component analysis of style manuals...............................................67 Comparative structure of Structured Authoring Workshop Guide.....74 Comparative structure of HATC424 syllabus.....................................75 Comparative structure of DITA Standards.........................................77 2 PhD Research Project - Anthony Self | Contents Final structure of the Artefact............................................................82 Writing approach..........................................................................................85 Putting the writing approach into practice.........................................88 Progression of Artefact TOC.............................................................89 How it was done: Using citations.......................................................91 Authoring and publishing tools.....................................................................92 Initial tools approach.........................................................................93 Revised tools approach.....................................................................94 Reflection.....................................................................................................95 What a DITA author needs................................................................95 Content model...................................................................................97 Testing ideas in Europe, November 2009.........................................97 How the Artefact was created....................................................................100 How it was done: Migration from Author-it to DITA..........................100 How it was done: Links to Language Reference.............................101 How it was done: Links to Microsoft Manual of Style......................102 How is was done: Private author comments in topics.....................103 How it was done: Audit trail.............................................................104 How it was done: Moving conref Source without a CMS.................104 How it was done: Nomenclature......................................................106 How it was done: Exemplars and sample topics.............................106 How it was done: Rules and importance attributes.........................107 How it was done: Ensuring all DITA elements were covered..........108 How it was done: American English................................................109 How it was done: Using citations.....................................................110 Chapter 5: Essays.........................................................112 Relationship between Essays and Artefact................................................115 The nub of the best practice problem: stem sentences.............................117 The importance of DITA as a standard......................................................119 The content model for Artefact and Exegesis content...............................121 Reflections on writing short descriptions...................................................123 Thesis statements in short descriptions.....................................................125 Citations in base content model DITA........................................................126 Benefits of content re-use..........................................................................130 Using indexes with conditional publishing..................................................131 Writing to STOP.........................................................................................132 STOP and DITA..........................................................................................135 Writing paragraphs.....................................................................................136 Using journalistic techniques in structured technical communication........137 Changes in technical communication practice...........................................139 Levels of re-use..........................................................................................140 DITA schema declarations.........................................................................142 Constraints in DITA 1.2..............................................................................143 Filtering and flagging content in DITA........................................................144 3 PhD Research Project - Anthony Self | Contents Variables: conrefs or attributes?.................................................................145 DITA and semantics...................................................................................147 Escape from Author-it................................................................................148 DITA and Content Management Systems..................................................152 The Artefact and Miller's Law.....................................................................153 Approaches to procedural topics...............................................................153 Making decisions to remove context..........................................................154 Improved glossary and terminology handling............................................155 Examples of letter case in titles.................................................................162 Separation of content and form in People and Place Style Sheet.............163 Semantic elements for user documentation...............................................165 Conclusion....................................................................................172 What constitutes best practice in DITA?....................................................172 References....................................................................................173 Bibliography...............................................................................................173 Appendix A: Academic Papers....................................184 DITA and the Challenges of Single Source Publishing..............................185 Abstract...........................................................................................185 DITA................................................................................................185 Case Study......................................................................................186 Separation of content and form in four style guides........................189 The Challenges of Editing in Single-Sourced Publications.............190 The Challenge of Content Re-use...................................................193