Workshop: XML and Structure Simon Bate Scriptorium Publishing
About me <ul><li>Simon Bate
Sr. Technical Consultant at Scriptorium
Certified Technical Trainer
30+ years Tech Comm experience
5 years of DITA and DITA OT experience </li></ul>
About Scriptorium <ul><li>Content Strategy for Technical Communication
Analyze
Develop strategy
Implement
Transform
Train </li></ul>
Overview <ul><li>Structured Authoring
XML
Authoring Topics </li><ul><li>Exercise </li></ul><li>Editing for re-use </li><ul><li>Exercise </li></ul></ul>
What is Structured Authoring? <ul><li>A publishing workflow that defines and enforces consistent organization of informati...
Typically implemented with software that verifies whether units of content follow a structure definition template </li></ul>
In Structured Authoring <ul><li>Content, organization, and presentation are separated
Elements and content identified with semantic tags
Formatting is automated
Formats are determined by  </li><ul><li>tags
and context
and order </li></ul><li>Different outputs can have different format rules </li></ul>
Elements and hierarchy <ul><li>Elements are units of content.
Elements contain text or other elements.
Elements are organized in a hierarchical structure tree.
Elements have a relationship to one another. </li></ul>
XML Overview <ul><li>Definition
Syntax
Defining structure </li></ul>
XML definition <ul><li>eXtensible Markup Language
Developed by W3C
Successor to SGML and HTML </li></ul>
XML Syntax <ul><li>Angle brackets for elements </li><ul><li><element>This is text in an element</element> </li></ul><li>At...
XML is well-formed when: <ul><li>Syntax rules are followed.
Elements are opened and closed.
Upcoming SlideShare
Loading in …5
×

Post conference workshop (xml and structure)

773 views

Published on

Post-conference workshop at tcworld India 2012. Provides background on structured authoring, XML, planning your topics, writing topics, and writing for re-use.

Published in: Technology, News & Politics
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
773
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
7
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Post conference workshop (xml and structure)

  1. 1. Workshop: XML and Structure Simon Bate Scriptorium Publishing
  2. 2. About me <ul><li>Simon Bate
  3. 3. Sr. Technical Consultant at Scriptorium
  4. 4. Certified Technical Trainer
  5. 5. 30+ years Tech Comm experience
  6. 6. 5 years of DITA and DITA OT experience </li></ul>
  7. 7. About Scriptorium <ul><li>Content Strategy for Technical Communication
  8. 8. Analyze
  9. 9. Develop strategy
  10. 10. Implement
  11. 11. Transform
  12. 12. Train </li></ul>
  13. 13. Overview <ul><li>Structured Authoring
  14. 14. XML
  15. 15. Authoring Topics </li><ul><li>Exercise </li></ul><li>Editing for re-use </li><ul><li>Exercise </li></ul></ul>
  16. 16. What is Structured Authoring? <ul><li>A publishing workflow that defines and enforces consistent organization of information in documents
  17. 17. Typically implemented with software that verifies whether units of content follow a structure definition template </li></ul>
  18. 18. In Structured Authoring <ul><li>Content, organization, and presentation are separated
  19. 19. Elements and content identified with semantic tags
  20. 20. Formatting is automated
  21. 21. Formats are determined by </li><ul><li>tags
  22. 22. and context
  23. 23. and order </li></ul><li>Different outputs can have different format rules </li></ul>
  24. 24. Elements and hierarchy <ul><li>Elements are units of content.
  25. 25. Elements contain text or other elements.
  26. 26. Elements are organized in a hierarchical structure tree.
  27. 27. Elements have a relationship to one another. </li></ul>
  28. 28. XML Overview <ul><li>Definition
  29. 29. Syntax
  30. 30. Defining structure </li></ul>
  31. 31. XML definition <ul><li>eXtensible Markup Language
  32. 32. Developed by W3C
  33. 33. Successor to SGML and HTML </li></ul>
  34. 34. XML Syntax <ul><li>Angle brackets for elements </li><ul><li><element>This is text in an element</element> </li></ul><li>Attributes inside element name </li><ul><li><element attribute=&quot;my attribute&quot;>This is text in an element</element> </li></ul><li>Empty tags are allowed </li><ul><li><element attribute=&quot;my attribute&quot;/> </li></ul></ul>
  35. 35. XML is well-formed when: <ul><li>Syntax rules are followed.
  36. 36. Elements are opened and closed.
  37. 37. Empty elements are closed.
  38. 38. Attributes are quoted.
  39. 39. Element boundaries do not cross </li><ul><li>Tags are properly nested. </li></ul></ul>
  40. 40. XML is valid when: <ul><li>The sequence of the tags follows a defined structure.
  41. 41. Structure can be defined by: </li><ul><li>Document Type Definition (DTD)
  42. 42. Schema </li></ul><li>XML document indicates DTD or schema
  43. 43. Structure declares </li><ul><li>Content model
  44. 44. Attributes and possible values </li></ul></ul>
  45. 45. XML and Structured Authoring Structured Authoring XML A concept A technology Adds hierarchy to information Expresses hierarchical information Adds consistency to information Provides mechanisms for ensuring consistency Does not require XML Does not have to be structured
  46. 46. Implementing structured workflow <ul><li>Goals and metrics
  47. 47. Roles
  48. 48. Milestones
  49. 49. Structure analysis
  50. 50. Structure definition
  51. 51. Pilot </li></ul><ul><li>Legacy strategy
  52. 52. Training
  53. 53. Documentation
  54. 54. Change management
  55. 55. Transition support
  56. 56. Evaluation </li></ul>
  57. 57. Structured writing basics <ul><li>What the creators say: </li><ul><li>[Media-neutral content] follows the same basic information design principles that have informed good manual design and good online design for decades: task orientation, minimalism, and scenario-based development. – Don Day et al in WinWriters.com </li></ul></ul>
  58. 58. Structured writing is: <ul><li>Modular
  59. 59. Concise
  60. 60. Focused
  61. 61. Free-standing
  62. 62. Audience-specific
  63. 63. Self-labeling </li></ul>
  64. 64. <ul>Modular </ul><ul><li>Create a series of individual topics
  65. 65. Can be re-organized later
  66. 66. Not narrative </li></ul>
  67. 67. Concise <ul><li>To the point
  68. 68. Only provides the necessary information
  69. 69. Active voice
  70. 70. Present tense </li></ul>
  71. 71. Focused <ul><li>One idea (or task) per topic.
  72. 72. Identifiable purpose </li></ul>
  73. 73. Free-standing <ul><li>Each topic stands on its own.
  74. 74. Contains enough information </li></ul>
  75. 75. Audience-specific <ul><li>Addresses a single audience
  76. 76. Don't make the reader look for their section
  77. 77. Can use filtering </li></ul>
  78. 78. Self-labeling <ul><li>Label information with metadata </li><ul><li>as appropriate </li></ul><li>Don't depend on file names </li><ul><li>CCMS often drop them </li></ul></ul>
  79. 79. Analyze information <ul><li>Find the major tasks </li><ul><li>Task-oriented documentation
  80. 80. Often from Marketing use cases
  81. 81. Talk with developers
  82. 82. Work with product </li></ul><li>Divide tasks into sub tasks
  83. 83. Identify necessary concepts
  84. 84. Identify reference information </li></ul>
  85. 85. Exercise: “How to read a book” <ul><li>Identify task, concept, and reference topics </li><ul><li>Related to reading books
  86. 86. For example: </li><ul><li>Selecting reading material
  87. 87. Types of books
  88. 88. Dealing with paper cuts </li></ul></ul><li>Write a task and a concept
  89. 89. http://www.youtube.com/watch?v=LRBIVRwvUeE </li></ul>
  90. 90. Writing for reuse <ul><li>Consistency
  91. 91. Context-free
  92. 92. Generalized
  93. 93. Reuse techniques </li></ul>
  94. 94. Consistency <ul><li>Consistency in topic depth and length
  95. 95. Consistency of tagging and usage </li><ul><li>Use a Style Guide
  96. 96. Or agree on usage </li></ul><li>Neutral voice </li><ul><li>Limited vocabulary
  97. 97. Limit use of pronouns </li><ul><li>Particularly gender-specific pronouns </li></ul><li>Avoid idioms and colloquialisms </li></ul></ul>
  98. 98. Context-free <ul><li>Do not assume context </li><ul><li>Avoid “previous”, “next”, “earlier”, “later” </li></ul><li>Do not assume document type </li><ul><li>Avoid “In this chapter...” </li></ul><li>Inline cross-references discouraged. </li><ul><li>Use relationship table </li></ul></ul>
  99. 99. Generalized <ul><li>Don't be too specific </li><ul><li>you'll regret it later </li></ul><li>Unless it's crucial
  100. 100. “Gratuitious” adjectives </li><ul><li>Number
  101. 101. Size
  102. 102. Color </li></ul></ul>
  103. 103. Reuse techniques <ul><li>Fragments
  104. 104. Filtering
  105. 105. Maps </li></ul>
  106. 106. Fragments <ul><li>Chunks of text that can be re-used
  107. 107. Should be at least a paragraph (or other block) </li><ul><li>English pronoun agreement
  108. 108. Localization issues </li></ul><li>By design </li><ul><li>Legal notices </li></ul><li>By discovery </li><ul><li>Repeated text in current doc
  109. 109. Or other docs </li></ul></ul>
  110. 110. Filtering <ul><li>Conditions
  111. 111. Single source, multiple audiences </li><ul><li>Platform (Mac, PC, Linux)
  112. 112. User level (beginner, advanced)
  113. 113. Permissions (user, super user)
  114. 114. Product or product version </li></ul></ul>
  115. 115. Maps <ul><li>Organizing topics
  116. 116. Individual topics reused in different documents
  117. 117. Examples </li><ul><li>Boilerplate or regulated text
  118. 118. Common sets of instructions
  119. 119. Product descriptions
  120. 120. Company history </li></ul><li>Don't think topic = page = section = chapter </li></ul>
  121. 121. Exercise <ul><li>Editing for reuse
  122. 122. Review and mark up the sample
  123. 123. Look for </li><ul><li>Consistency
  124. 124. Context
  125. 125. Colloquialisms
  126. 126. Pronouns
  127. 127. Possible fragments
  128. 128. Possibly filtered text </li></ul></ul>
  129. 129. Structured writing summary <ul><li>Most of these guidelines are simply good writing
  130. 130. Small inconsistencies that are OK in writing books cause problems in modular content </li><ul><li>Keywords/index entries
  131. 131. Terminology </li></ul><li>Writing for reuse requires more consistency, discipline, and consideration </li></ul>
  132. 132. Questions?
  133. 133. Contact information Simon Bate Scriptorium Publishing www.scriptorium.com [email_address] twitter: @simonbate +1.919.433.2606

×