Download pdf - Deep Dive: Structured XML Authoring with George Bina, oXygen XML Editor

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



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



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



Need for speed



Need for speedstructure



Need for speedstructure Is a simple text file structured?



Need for speedstructure Is a simple text file structured? Yes!







explicit structure text lines




explicit structure text lines

implicit structure Wtle abstract quote subWtle



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



XML enables explicit structure



Just the XML syntax is not enough…



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.



Technical documentaWon One of the main use-‐cases for XML An important area for many oXygen users Usual choices: •  DITA •  DocBook •  Custom XML vocabulary



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!



Create high quality structured content Make XML authoring easier by guiding users to choose correct markup and idenWfying potenWal problems early on



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



What content should I create here?



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



What should I put in this document?



What should I put in this document?



What XML markup should I choose?



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















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.



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



How should I …?

Inline acWons

Use this to add a new choice table



How should I …?

Use this to insert a new row



How should I …?



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)



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



Something wrong with my content?

Empty descripWon

Valid document



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



How can we enforce rules on content?



How can we enforce rules on content?



Adding rules as part of a style guide

Rule text

Rule definiWon



Adding rules as part of a style guide



Technologies CSS staWc content



Technologies Element toolWps: annotaWons and configuraWon



Technologies Custom acWons



Technologies Rules enforced with ISO Schematron



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



Example “The Language of Content Strategy “ book by Scof Abel and Rahel Anne Bailie



Book



Book



Cards



Website hfp://thelanguageofcontentstrategy.com/



oXygen framework hfps://github.com/oxygenxml/languageBook Open source, Apache 2.0 license



Book layout -‐ chapter



Book layout -‐ topic



Card layout



Full layout



AcWons and editable references



Schematron rules



Review and change tracking



More examples •  If we have Wme…



Thank you! QuesWons?

George Bina [email protected] @georgebina hfp://www.oxygenxml.com