TCUK 2012, Tony Self, DITA Style Guide
Download as PPTX, PDF3 likes1,533 views
- The document discusses the need for a style guide for the Darwin Information Typing Architecture (DITA) to promote consistency in technical authoring and help with adoption of DITA. - Traditional style manuals focus on style-based authoring but DITA uses semantic authoring, so an new DITA style guide is needed to document standards and conventions. - The proposed DITA style guide would cover topics like which elements to use for key terms and keyboard keys to ensure consistent markup across projects. It could help interpret the large DITA language reference and resolve issues open to debate.
TCUK 2012, Tony Self, DITA Style Guide
- 1. A Style Guide for DITA Authoring Tony Self tony.self@hyperwrite.com
- 2. Context • “Informed” by academic research at Swinburne University • What constitutes best practice in the Darwin Information Typing Architecture for technical publications?
- 3. A Style Guide for Authoring Documents in DITA
- 4. What is DITA again? • DITA is a new open standard for the creation and management of written documents such as policies and procedures, teaching and learning documents, Help systems, Web sites and instruction manuals. • DITA is many things in one. It is: – an XML language – a writing methodology – a topic-based information architecture – a structured authoring platform.
- 5. For Tech Writers... • The DITA approach utterly separates content from its presentation by using document semantics as the basis for mark-up. • It takes a modular approach • It is very different from the existing methods of: – linear writing – style-based markup
- 6. Two differences to focus on • Separation of content and form – Author not concerned with presentational form • Modularity – Documents written as re-useable components
- 8. 1985? • No Web • No mobile phone • No iPod • No MP3 • No digital cameras • No Java, XML, HTML • Y2K still 15 years away
- 9. Three Ages of Tech Writing • Before computerisation – Long-hand – Demarcation of skills • Computerisation – Word processors (WordPerfect, Word) – Desktop publishing (Ventura, PageMaker, FrameMaker) • Modular – XML-based – Methodologies (eg, DITA)
- 10. Influences on Tech Comms Globalisation Embedded UA Modularity Agile Technical Communication Re-use Dublin Core Single-sourcing Facets
- 11. The Need for a DITA Style Guide
- 12. What is a Style Manual? • A set of standards governing the design and writing of documents. • Usually takes the form of a printed manual. • Originators: publishing organisations, standards bodies, government agencies and publication departments • Examples: – AGPS Style Manual – Chicago Manual of Style – News Limited Style
- 13. Need for a DITA Style Manual • Style manuals promote consistency – Leading to authority – and readability • Existing Style Manuals focus on style- based authoring, and most are entirely unsuitable for semantic authoring • One of the difficulties of DITA adoption is working without a relevant Style Manual
- 14. Style Guide Content vs Form 45% Style Manual for Authors, Editors and Printers 55% 58% Style Book – A Guide for New Zealand Writers and Editors 42% Content (Editorial) Style Presentational Style
- 15. Style Guide Content vs Form 30% Chicago Manual of Style 70% News Limited Style 100% Content (Editorial) Style Presentational Style
- 16. “Traditional” Style Manual Use
- 17. DITA Style Manual Need
- 18. How style guides work • Document the standards and conventions used • Policed by the manager or editor • Self-policed by authors themselves • Example – a style guide might stipulate that: – Each topic should have a primary heading that describes the content of the topic. • DITA's language reference is a type of style guide • But many requirements can be policed by the validating editor – For example, a topic cannot be saved unless it has a title
- 19. DITA Style Manual • Supra-organisational semantic mark-up rules • Important when the formal language rules themselves are open to interpretation – <varname> or <apiname>? – <term> or <ph> or <keyword>? • DITA Language Reference is large, technical, and impenetrable for “non-technical” technical authors • Example – Stem sentence followed by a list • Authority (eventually) of Style Manual via open source, community ownership
- 20. Example
- 21. DITA Language Reference • The command (<cmd>) element is required as the first element inside a <step>. It provides the active voice instruction to the user for completing the step, and should not be more than one sentence. If the step needs additional explanation, this can follow the <cmd> element inside an <info> element.
- 22. The DITA Style Guide What Element for Keystrokes? It is not immediately obvious in DITA what element should be used to mark up keyboard keys, such as Enter, Ctrl and Backspace. The best approach is to use the uicontrol and userinput elements, depending on context. When describing keys on a computer keyboard, use the uicontrol element. For example: <p>Use the <uicontrol>Tab<uicontrol> to move from field to field.</p> Note: Do not use the shortcut element; this element is intended to identify keyboard shortcuts in descriptions of user interface controls in windowed applications.
- 23. Potential for controversy • What if you disagree? • Paragraphs within list items • Lists within stem sentence paragraph • Serial commas • For example, no punctuation at the end of list items • Not a matter of right or wrong, but a means of achieving consistency
- 24. The DITA Style Guide • Chapter 1 – Topics and Information Types • Chapter 2 – DITA Map Files • Chapter 3 – Syntax and Markup • Chapter 4 – Language and Punctuation • Chapter 5 – Graphics and Figures • Chapter 6 – Cross-referencing • Chapter 7 – Content Re-use • Chapter 8 – Metadata and Filtering • Chapter 9 – Documentation Process
- 27. More information • www.ditastyle.com • www.scriptorium.com/books/the-dita- style-guide-best-practices-for-authors/
Editor's Notes
- #3: While the DITA technical standard is precise, the DITA approach itself is not universally understood or agreed. Working with DITA is made difficult by the lack of agreed common practices, let alone best practice. Common practices must be adopted so that the advantages of the modular, XML-based DITA document architecture can be reached.This action research project by artefact and exegesis is intended to identify what constitutes best practice in DITA authoring. The product of the research is a style manual, has just been published by Scriptorium in both paper and electronic form. In the medium term, the Style Guide will be donated to the community as an open source Wiki.
- #4: This raises the first question of my presentation.... What is DITA?I’m not going to answer completely straight away, because I have to build to it...
- #5: DITA is many things in one.
- #6: DITA is at the start of its life cycle. It was first released in 2005. DITA tools are now starting to mature, and DITA is now becoming viable for broad sections of the tech comms profession.End of Part I
- #8: There is some association with hypertext, which is also topic-based, and often modular. However, hypertext is a delivery format, whereas DITA is an authoring format.With a modular approach, one “work” can lead to many publications.
- #10: Existing style manuals come from the Computerisation age. Just as “before computerisation” style manuals became obsolete (even though there are good stuff in them), “computerisation” style manuals are also obsolete for XML authoring (even though there’s good stuff in them).Notice I’m talking about technical writing. Help authoring is perhaps no longer a separate endeavour from print authoring, due to the separation of content and form.
- #15: Style is a confusing word. The separation of content from form, in style guide terms, is the separation of editorial style from presentational style. You might say, well, can’t the News Limited Style manual be used? However, although it does indeed cover editorial style and not presentation style. As you can see, I have a wealth of things to document in the Exegesis.
- #16: Style is a confusing word. The separation of content from form, in style guide terms, is the separation of editorial style from presentational style. You might say, well, can’t the News Limited Style manual be used? However, although it does indeed cover editorial style and not presentation style.
- #21: The last point should be interesting. In order for the style manual to be useful, it has to be continually updated as the DITA standard evolves, and as other ideas and best practices reveal themselves. This is probably best managed by donating the Manual, and moving it to a Wiki format.