Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.

Structured writing presentation to London Content Strategy Meetup

Content can often seem like jelly - messy and hard to manage. In this presentation, we'll look at whether you can reduce this messiness through structured writing. In this overview of the topic, we'll explore what is structured writing, what it promises to give its adopters, the different standards, and the challenges that come with using structured writing.

If you've wanted to get a handle on structured content and how it could work to make your content work better, join us for this informative session.

Our presenter, Ellis Pratt, is a Consulting Technical Communicator and Director at Cherryleaf, a technical writing services company. He has been working in technical communication since the early 1990s. He has a degree in Business Studies. He is also:
- Member of the Institute of Scientific and Technical Communicators
- Associate of the Institution of Engineering and Technology
- An ISTC Management Council member

In 2017, he was listed as one of the top 25 Content Experience influencers in the world.

Ellis was a contributor to two books: Current Practices and Trends in Technical Communication, and The Language of Technical Communication.

  • Soyez le premier à commenter

Structured writing presentation to London Content Strategy Meetup

  1. 1. What's the deal about structured content? Ellis Pratt @ellispratt February 2018 London Content Strategy Meetup #contentLDN
  2. 2. Overview 1. About me, About you 2. In the olden days 3. What is structured writing? 4. The rise the machines 5. The standards 6. The problems 7. The future?
  3. 3. About me, About you
  4. 4. About me Director at Cherryleaf, a technical writing services and training company in the UK I’m also on the ISTC’s Management Council
  5. 5. About you Who has experience of structured writing?
  6. 6. In the olden days
  7. 7. In 1959…
  8. 8. Hughes-Fullerton Ground Systems Group
  9. 9. They needed to write lots of proposals How do we get the document finished on time? How do we work collaboratively? How do we maintain coherence? How do we control quality?
  10. 10. They devised STOP Sequential Thematic Organization of Proposals
  11. 11. Proposals were organised into a consistent sequence of themes The right page always showed a graphic  The left page had to contain explanatory text 
  12. 12. The Sixties
  13. 13. 1968 An academic called Robert Horn identified common types of information that account for nearly all the content of business and technical communication
  14. 14. Six “Information Blocks” Procedure A set of steps an individual performs to complete a single task Process A series of events, stages or phases that occurs over time and has a specific outcome Principle A statement designed to dictate, guide or require behavior Concept A class or group of things that share a critical set of attributes Structure A description or depiction of anything that has parts or boundaries Fact A statement that is assumed to be true (There are additional information blocks in Information Mapping)
  15. 15. Horn used this to develop the “Information Mapping” method
  16. 16. Information Mapping Standalone “Information Blocks” Conforming to rules on how to present the Information Blocks
  17. 17. Common features
  18. 18. Common elements 1. Information Types (topics) 2. Information maps
  19. 19. Achieved by Training all the writers in the method Having editors to act as quality controllers
  20. 20. The result Consistent documents of a high quality Improved clarity Improved findability Less writer’s block
  21. 21. What is structured writing?
  22. 22. What is structured writing? “Content that conforms to structural and semantic rules,  to meet specific business requirements.”
  23. 23. What is structured writing? Constrained writing
  24. 24. What is structured writing? A (information) model of the content journey
  25. 25. More examples from the olden days
  26. 26. Haynes manuals
  27. 27. Recipes?
  28. 28. The rise of the machines
  29. 29. Combining content
  30. 30. We want Automated processing of content
  31. 31. We want Topic reuse (Transclusion) To be able to manage variations
  32. 32. We also want Intelligent styling of publications Intelligent/personalised content Efficient translation
  33. 33. So what is structured writing, again? “Content that conforms to structural and semantic rules that allow machine processing  to meet specific business requirements.” Don Day
  34. 34. Use Cases
  35. 35. Policies and Procedures Have different audiences Need to vary by location
  36. 36. Product documentation Pro and Lite version Version 1 and Version 2 MacOS and iOS Training, Help and Support content
  37. 37. Ravelry.com
  38. 38. Intelligent chatbots Relate our content (response) to: Intents Entities User role and context
  39. 39. This is hard with Microsoft Word
  40. 40. It’s hard with Markdown and HTML, too I use 3 Heading levels You use 4 Heading levels
  41. 41. The different standards
  42. 42. Standards are like toothbrushes
  43. 43. Standards are like toothbrushes Everyone wants to use their own, not any one else’s.
  44. 44. Regulatory standards S1000D/ATA100 MILSpec
  45. 45. S1000D Modular content stored in a database Originally designed for aircraft, but later modified for use with land, sea, and commercial equipment
  46. 46. S1000D Information maps ATA No. ATA Chapter name ATA 00 GENERAL ATA 01 MAINTENANCE POLICY ATA 02 OPERATIONS ATA 03 SUPPORT ATA 04 AIRLINE USE Aircraft Handling ATA 05 TIME LIMITS/MAINTENANCE CHECKS ATA 06 DIMENSIONS AND AREAS ATA 07 LIFTING, SHORING AND JACKING ATA 08 LEVELING AND WEIGHING. ATA 09 TOWING AND TAXI ATA 10 PARKING, MOORING, STORAGE AND RETURN TO SERVICE ATA 11 PLACARDS AND MARKINGS ATA 12 SERVICING - ROUTINE MAINTENANCE ATA 14 HARDWARE AND GENERAL TOOLS
  47. 47. S1000D Information Types Crew/Operator Description Procedural Fault Illustrated Parts Data Schedules Wiring Process Module Business Rules Exchange
  48. 48. Other standards DocBook DITA
  49. 49. DITA Based on STOP, Information Mapping, and DocBook
  50. 50. Task topic example <task id="birdhousebuilding"> <title>Building a bird house</title> <shortdesc>Building a birdhouse is a perfect activity for adults to share with their children or grandchildren. It can be used to teach about birds, as well as the proper use of tools. </shortdesc> <taskbody> <context>Birdhouses provide safe locations for birds to build nests and raise their young. They also provide shelter during cold and rainy spells.</context> <prereq>To build a sound birdhouse, you will need a complete set of tools: <ul><li>hand saw</li> <li>hammer ... </li> </ul></prereq> <steps> <step><cmd>Lay out the dimensions for the birdhouse elements.</cmd></step> <step><cmd>Cut the elements to size.</cmd></step> <step><cmd>Drill a 1 1/2" diameter hole for the bird entrance on the front.</cmd> <info>You need to look at the drawing for the correct placement of the hole.</info></step> </steps> <result>You now have a beautiful new birdhouse!</result> <postreq>Now find a good place to mount it.</postreq> </taskbody> </task>
  51. 51. Reference topic example <reference id="oiltypes"> <title>Oil Types</title> <shortdesc>The tables provide the recommended oil types.</shortdesc> <refbody> <properties> <prophead> <proptypehd>Oil type</proptypehd> <propvaluehd>Oil brand</propvaluehd> <propdeschd>Appropriate use</propdeschd> </prophead> <property> <proptype>Primary oil</proptype> <propvalue>A1X<propvalue> <propdesc>Appropriate for one-cylinder engines</propdesc> </property> <property> <proptype>Secondary oil</proptype> <propvalue>B2Z</propvalue> <propdesc>Appropriate for two-cylinder engines</propdesc> </property> </properties> </refbody>
  52. 52. DITA Map example <map> <title>DITA work at OASIS</title> <topicref href="oasis-dita-technical-committees.dita"> <topicref href="dita_technical_committee.dita"/> <topicref href="dita_adoption_technical_committee.dita"/> </topicref> <!-- Contents of the oasis-processes.ditamap file --> <topicref href="oasis-processes.dita"> <!-- ... --> </topicref> <!-- ... --> </map>
  53. 53. Meanwhile in Germany
  54. 54. There are lots of standards The authoring tool vendors have their own standard for structured authoring “Intelligent Information Request and Delivery Standard” Metadata classification, by Product and Information
  55. 55. The problems
  56. 56. Semantic Markup
  57. 57. It’s strict and restrictive It’s constrained writing
  58. 58. What about your existing content? Do you convert it?
  59. 59. Orgs don’t want to do it After 10 years, approximately only 9% of technical communicators use DITA 9%
  60. 60. Simplifying DITA WYSIWYG editors
  61. 61. Simplifying DITA Lightweight DITA DITA Glass (virtual DITA topics via URLs)
  62. 62. The future?
  63. 63. Use forms? Headings must be marked semantically But the data must be more than plain text
  64. 64. Documentation as an API?
  65. 65. SPFE Use queries instead of maps You write a query expression that selects the topics to be included in a page based on their metadata. topic head identity tracking index  body topic-structures text-structures paragraphs mentions decorations
  66. 66. Topic-based writing would be a big step forward Every time you add a heading in a page, the software creates a topic stored in its own individual file
  67. 67. Topic-based writing would be a big step forward IA Writer has content blocks
  68. 68. AsciiDoc semantic markup? AsciiDoc is based on DocBook XML :summary: Asciidoctor is a mature, plain-text document format for writing notes = Reference Documentation Lead Developer This is documentation for project X. include::basics.adoc[] include::installation.adoc[] [.rolename]`monospace text`
  69. 69. Summary
  70. 70. Do we want? Automated processing of content Topic reuse To be able to manage variations
  71. 71. Do we want? Intelligent styling of publications Intelligent/personalised content Efficient translation
  72. 72. Do we face this? How do we get the document finished on time? How do we work collaboratively? How do we maintain coherence? How do we control quality?
  73. 73. Questions (I have laptop stickers to give away)
  74. 74. For more information ellis@cherryleaf.com @ellispratt © Cherryleaf 2018 Images and screenshots © their respective owners

×