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.

5. Deep
Dive:
XML
Structured
Authoring
George
Bina

6. 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

7. 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

8. 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

9. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Need
for
speed

10. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Need
for
speedstructure

11. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Need
for
speedstructure
Is
a
simple
text
file
structured?

12. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Need
for
speedstructure
Is
a
simple
text
file
structured?
Yes!

13. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Need
for
speedstructure
Is
a
simple
text
file
structured?
Yes!

14. 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

15. 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

16. 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

17. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
XML
enables
explicit
structure

18. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Just
the
XML
syntax
is
not
enough…

19. 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.

20. 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

21. 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!

22. 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

23. 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

24. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
What
content
should
I
create
here?

25. 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

26. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
What
should
I
put
in
this
document?

27. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
What
should
I
put
in
this
document?

28. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
What
XML
markup
should
I
choose?

29. 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

30. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
What
XML
markup
should
I
choose?

31. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
What
XML
markup
should
I
choose?

32. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
What
XML
markup
should
I
choose?

33. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
What
XML
markup
should
I
choose?

34. 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.

35. 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

36. 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

37. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
How
should
I
…?
Use
this
to
insert
a
new
row

38. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
How
should
I
…?

39. 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)

40. 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

41. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Something
wrong
with
my
content?
Empty
descripWon
Valid
document

42. 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

43. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
How
can
we
enforce
rules
on
content?

44. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
How
can
we
enforce
rules
on
content?

45. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Adding
rules
as
part
of
a
style
guide
Rule
text
Rule
definiWon

46. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Adding
rules
as
part
of
a
style
guide

47. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Technologies
CSS
staWc
content

48. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Technologies
Element
toolWps:
annotaWons
and
configuraWon

49. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Technologies
Custom
acWons

50. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Technologies
Rules
enforced
with
ISO
Schematron

51. 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

52. 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

53. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Book

54. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Book

55. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Cards

56. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Website
hfp://thelanguageofcontentstrategy.com/

57. 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

58. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Book
layout
-­‐
chapter

59. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Book
layout
-­‐
topic

60. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Card
layout

61. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Full
layout

62. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
AcWons
and
editable
references

63. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Schematron
rules

64. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Review
and
change
tracking

65. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
More
examples
• If
we
have
Wme…

66. Copyright
@
Syncro
So<,
2014.
All
rights
reserved.
Deep
dive:
XML
Structured
Authoring
Thank
you!
QuesWons?
George
Bina
george@oxygenxml.com
@georgebina
hfp://www.oxygenxml.com