Upload
scott-abel
View
539
Download
0
Embed Size (px)
DESCRIPTION
George Bina explores the world of XML authoring for technical documentation. He shares tips and tricks designed to help technical communicators understand the advanced information management capabilities structured XML authoring provides over traditional authoring approaches. Specifically, George addresses the following questions: How do I know what content to create? What XML markup should I choose and why? How do I leverage markup to engineer better authoring experiences? How to we enforce content rules in XML documents? Why correcting content problems during the authoring process can help you reduce costs? This session was part of The Content Wrangler Virtual Summit on Advanced Technical Communication Practices, December 4-5, 2014. Hosted by BrightTALK. Sponsored by SDL, Astoria Software, Acrolinx, oXygen XML Editor, Logos, Scriptorium, and Oberon Technologies.
Citation preview
Deep Dive: XML Structured Authoring George Bina
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
About oXygen XML Editor • 2001 – XML IDE
– Develop XML grammars (DTD, XML Schema, Relax NG) – Publish/transform documents (XSLT, ant, XProc) – Query and manage XML (XQuery, XML databases) – Give access to your data though web services (WSDL)
• 2007 – XML visual ediWng based on CSS – Create XML in a word processor like interface – Guided XML ediWng for non technical people
• 2013 – XML authoring across devices – Use any HTML5-‐aware device, including mobile devices
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
About me • 15+ years of working with XML • Founder of Syncro So< / oXygen XML Editor • Involved in XML related open source projects • Speaking at many conference on oXygen and XML related topics
• Try to bring interesWng ideas to life
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Purpose of this presentaWon • Respond to a few quesWons – Why structured informaWon? – How can we improve the user experience when creaWng structured informaWon?
– How can we make sure we obtain high-‐quality informaWon?
• Get an idea of what technologies and opWons are available to improve the quality of your structured informaWon
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Need for speed
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Need for speedstructure
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Need for speedstructure Is a simple text file structured?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Need for speedstructure Is a simple text file structured? Yes!
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Need for speedstructure Is a simple text file structured? Yes!
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Need for speedstructure Is a simple text file structured? Yes!
explicit structure text lines
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Need for speedstructure Is a simple text file structured? Yes!
explicit structure text lines
implicit structure Wtle abstract quote subWtle
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Explicit versus implicit structure Explicit structure
– Can be easily processed automaWcally by a machine – Can be verified against a specified pafern
Implicit structure – Requires domain knowledge to be understood and a very intelligent audience
– Can take different forms, it is difficult to enforce a specific pafern
– Cannot be reliably processed automaWcally Explicit structure enables speed of informa4on processing
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
XML enables explicit structure
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Just the XML syntax is not enough…
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
XML is more than its syntax You get access to an enWre ecosystem • Grammars to define structure and already defined standard
vocabularies • Parsers, validators, processing languages • Authoring tools • XML Databases • Content Management Systems • Publishing workflows or delivery plalorms • Etc.
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Technical documentaWon One of the main use-‐cases for XML An important area for many oXygen users Usual choices: • DITA • DocBook • Custom XML vocabulary
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Quality The quality of an XML-‐based system depends on the quality of the XML markup that is entered into that system This happens when the XML is created, usually at authoring 4me!
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Create high quality structured content Make XML authoring easier by guiding users to choose correct markup and idenWfying potenWal problems early on
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Communicate with the author QuesWons an author may ask: • How do I know what content to create?
– Tell the author what is expected to appear in the document he writes and how that should be encoded
• What XML markup should I choose and why? – Let the author know what each XML element and afribute is intended for
• How can I perform complex tasks easier? – Provide acWons to simplify complex markup changes
• Is there something wrong with my current content? – IdenWfy potenWal issues and noWfy the author immediately
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
What content should I create here?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
What should I put in this document? Tell the author what is expected to appear in the document he writes and how that should be encoded • Where? – Within the document
• How? – InstrucWons and examples rendered directly within the document
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
What should I put in this document?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
What should I put in this document?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
What XML markup should I choose?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
What XML markup should I choose? Let the author know what each element and afribute is intended for • When? – When the author wants to insert or change markup
• How? – ToolWps describing the intended use of an element, afribute or value
– Progressive disclosure as links for more details to external resources
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
What XML markup should I choose?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
What XML markup should I choose?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
What XML markup should I choose?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
What XML markup should I choose?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
How should I …? • …insert a table, a table row, a table column • …reorder steps in a procedure • …change from an unordered list to an ordered list
• etc.
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
How should I …? Provide acWons to simplify markup changes • Where? – Menu, contextual menu, toolbar – Within the document
• How? – Define a set of custom acWons that match high level user concepts and make them available in different places in the user interface
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
How should I …?
Inline acWons
Use this to add a new choice table
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
How should I …?
Use this to insert a new row
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
How should I …?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Cost associated to fixing an issue Increases as Wme passes from zero to very expensive:
– Authoring (close to zero) – Review – Publishing – ProducWon (may not be acceptable anymore)
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Example • Problem – Use short descripWons for befer search results
• Possible soluWons – Instruct the writers – Ask reviewers to verify – Build checks into a QA tool – Build checks into the authoring tool
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Something wrong with my content?
Empty descripWon
Valid document
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
How can we enforce rules on content? IdenWfy potenWal issues and noWfy the author immediately • When? – As soon as the issue appears
• How? – Inform the author about the issue and provide hints on what to do to solve that problem
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
How can we enforce rules on content?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
How can we enforce rules on content?
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Adding rules as part of a style guide
Rule text
Rule definiWon
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Adding rules as part of a style guide
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Technologies CSS staWc content
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Technologies Element toolWps: annotaWons and configuraWon
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Technologies Custom acWons
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Technologies Rules enforced with ISO Schematron
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Conclusions • Structured content enables speed of processing • Quality of structured content can be achieved if we communicate
with the authors • CommunicaWon enables a befer authoring experience:
– Minimal or no training required to create structured content – Users can focus on their domain, on the informaWon they want to
encode and not on the encoding itself – The document becomes the complete user interface and drives the
authoring experience • Structured authoring may be easier than working with a word
processing applicaWon
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Example “The Language of Content Strategy “ book by Scof Abel and Rahel Anne Bailie
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Book
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Book
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Cards
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Website hfp://thelanguageofcontentstrategy.com/
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
oXygen framework hfps://github.com/oxygenxml/languageBook Open source, Apache 2.0 license
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Book layout -‐ chapter
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Book layout -‐ topic
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Card layout
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Full layout
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
AcWons and editable references
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Schematron rules
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Review and change tracking
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
More examples • If we have Wme…
Copyright @ Syncro So<, 2014. All rights reserved.
Deep dive: XML Structured Authoring
Thank you! QuesWons?
George Bina [email protected] @georgebina hfp://www.oxygenxml.com