Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.
Aiming for Best Practice in DITA           Authoring              Tony Self     tony.self@hyperwrite.com
Context• “Informed” by academic research at  Swinburne University• What constitutes best practice in the  Darwin Informati...
What is “best practice”?• Different things to different people• Bit like “quality”• “Better practice”• The adoption of wor...
Aiming for best practice•   Understand different alternatives•   Minimise inefficiencies•   Reduce process bottlenecks•   ...
Conventional best practice• Standard editing marks• Standard spelling• Standard punctuation rules• Standard paper sizes• S...
A Style Guide forAuthoring Documents in DITA
Big Picture
What is DITA again?• DITA is a new open standard for the creation  and management of written documents such  as policies a...
For Tech Writers...• The DITA approach utterly separates  content from its presentation by using  document semantics as th...
Two differences to focus on• Separation of content and form  – Author not concerned with presentational    form• Modularit...
DifferentApproaches
Influences on Tech Comms   Globalisation           Embedded UA                                          Modularity Agile  ...
Separation of Content and Form
Separation of Content• DITA incorporates the idea of the  separation of content from formatting  (and delivery)• Documents...
Workflow
Separation with Semantics• Author:  – Mark up the document using semantic    entities  – Do not consider page size, font, ...
Separation with Semantics• Information Architect:  – Define which topics need writing  – Assemble those topics into collec...
Separation with Semantics• Styling and aesthetic presentation is  another job, perhaps for a different  person (graphic de...
Everything is Different• The semantic authoring approach might  be alien...  – and the modular approach  – and the re-use ...
The Need for a DITA Style Guide
What is a Style Manual?• A set of standards governing the design and  writing of documents.• Usually takes the form of a p...
Need for a DITA Style Manual• Style manuals promote consistency  – Leading to authority  – and readability• Existing Style...
Style Guide Content vs Form
Style Guide Content vs Form
“Traditional” Style Manual Use
DITA Style Manual Need
How style guides work•   Document the standards and conventions used•   Policed by the manager or editor•   Self-policed b...
Interchange• WOOO  – Write Once and Once Only• Company supplying components to  manufacturer should supply documentation• ...
DITA Style Manual• Supra-organisational semantic mark-up rules• Important when the formal language rules  themselves are o...
Examples
DITA Language Reference• The command (<cmd>) element is  required as the first element inside a  <step>. It provides the a...
The DITA Style Guide• Short Description used throughoutWhat element for keystrokes?The uicontrol element should be used wh...
The DITA Style GuideWhat Element for Keystrokes?It is not immediately obvious in DITA what element   should be used to mar...
Potential for controversy• What if you disagree?• Paragraphs within list items• Lists within stem sentence paragraph• Seri...
Questions, Discussion, Ideas
More information• www.ditastyle.com• www.scriptorium.com/books/the-dita-  style-guide-best-practices-for-authors/
Upcoming SlideShare
Loading in …5
×

Webcast: DITA Best Practices

3,078 views

Published on

In this webcast hosted by Scriptorium Publishing, author Tony Self discusses his new book, The DITA Style Guide, and how it fits into a DITA workflow.

Published in: Technology
  • Sex in your area is here: ♥♥♥ http://bit.ly/2F90ZZC ♥♥♥
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Dating for everyone is here: ❶❶❶ http://bit.ly/2F90ZZC ❶❶❶
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Unlock Her Legs - How to Turn a Girl On In 10 Minutes or Less...  http://t.cn/AijLRbnO
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • FREE TRAINING: "How to Earn a 6-Figure Side-Income Online" ... ♥♥♥ https://bit.ly/2kS5a5J
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (Unlimited) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download Full EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ACCESS WEBSITE for All Ebooks ......................................................................................................................... Download Full PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here

Webcast: DITA Best Practices

  1. 1. Aiming for Best Practice in DITA Authoring Tony Self tony.self@hyperwrite.com
  2. 2. Context• “Informed” by academic research at Swinburne University• What constitutes best practice in the Darwin Information Typing Architecture for technical publications?
  3. 3. What is “best practice”?• Different things to different people• Bit like “quality”• “Better practice”• The adoption of work practices that reflect the most efficient and effective that are practically possible.• Few achieve best practice, but many aim for it!
  4. 4. Aiming for best practice• Understand different alternatives• Minimise inefficiencies• Reduce process bottlenecks• Choose effective methods• Standardise
  5. 5. Conventional best practice• Standard editing marks• Standard spelling• Standard punctuation rules• Standard paper sizes• Standard writing tools• Standard printing metrics• Presentation conventions• Methodologies• Captured in a style guide
  6. 6. A Style Guide forAuthoring Documents in DITA
  7. 7. Big Picture
  8. 8. 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.
  9. 9. 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
  10. 10. Two differences to focus on• Separation of content and form – Author not concerned with presentational form• Modularity – Documents written as re-useable components
  11. 11. DifferentApproaches
  12. 12. Influences on Tech Comms Globalisation Embedded UA Modularity Agile Technical CommunicationRe-use Dublin Core Single-sourcing Facets
  13. 13. Separation of Content and Form
  14. 14. Separation of Content• DITA incorporates the idea of the separation of content from formatting (and delivery)• Documents authored in a neutral format• For presentation and delivery to the reader, source documents need to be transformed into a reading format• Build, compile, publish, transform
  15. 15. Workflow
  16. 16. Separation with Semantics• Author: – Mark up the document using semantic entities – Do not consider page size, font, colour, indent, margin, leading, spacing, headers, footers, bolding, kerning, padding, alignment and numbering – Concentrate on getting the semantic markup right – Topic level focus: write topics, not documents
  17. 17. Separation with Semantics• Information Architect: – Define which topics need writing – Assemble those topics into collections – May be same person as author, but roles are distinct – Planning separated from writing
  18. 18. Separation with Semantics• Styling and aesthetic presentation is another job, perhaps for a different person (graphic designer)• Some styling jobs become XSL-FO or XSL- T programming jobs• Generating the document is another process (publishing)
  19. 19. Everything is Different• The semantic authoring approach might be alien... – and the modular approach – and the re-use philosophy – and the minimalism theory• Makes authoring entirely different
  20. 20. The Need for a DITA Style Guide
  21. 21. 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
  22. 22. 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
  23. 23. Style Guide Content vs Form
  24. 24. Style Guide Content vs Form
  25. 25. “Traditional” Style Manual Use
  26. 26. DITA Style Manual Need
  27. 27. 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 content.• DITAs 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
  28. 28. Interchange• WOOO – Write Once and Once Only• Company supplying components to manufacturer should supply documentation• Component document “consumed” by assembly document• Relies on the same application of the standard• The DITA standard has gaps
  29. 29. 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
  30. 30. Examples
  31. 31. 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.
  32. 32. The DITA Style Guide• Short Description used throughoutWhat element for keystrokes?The uicontrol element should be used when describing keys on a keyboard, and the userinput element for describing keystrokes that the user must input.• More detailed explanation and tool neutral mark-up examples
  33. 33. The DITA Style GuideWhat 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.
  34. 34. 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
  35. 35. Questions, Discussion, Ideas
  36. 36. More information• www.ditastyle.com• www.scriptorium.com/books/the-dita- style-guide-best-practices-for-authors/

×