Slides from my presentation at Barcelona Content Strategy Meetup, 20 October 2014. Defines structured writing, and discusses how it differs from other forms, what it means for writers, and how it's managed.

1. STRUCTURED WRITING
What’s
It
Good
For?
RAY
G ALLON
C U LT U R E C O M
TRA
THE
SO CI
ION
MAT
SFOR
N
ETY
Presentation
©
2013
Ray
Gallon
all
rights
reserved

2. What Is Structured Writing?
Structured
Writing
means
writing
self-­‐sufficient,
semantically
tagged
chunks
of
information
that
include
relevant
metadata.
Information
chunks
are
reusable
in
a
variety
of
situations,
providing
write
once,
publish
everywhere
capability.
Semantic
tagging
has
no
display
information.
Display
is
controlled
separately
and
is
context
dependent.
Chunks
can
be
grouped
together
in
containers,
and
can
inherit
characteristics
of
the
container.
Metadata
in
chunks
can
be
used
for
automating
certain
processes.
Presentation
©
2013
Ray
Gallon
all
rights
reserved

3. HTTP://WWW.BBC.CO.UK/FOOD/RECIPES/PIZZA_EXPRESSED_THREE_77124
Recipe
Preparation
Steps
!
step
step
step
Video
!
Ingredients
Pizza
dough
ingredient
ingredient…
Topping
ingredient
ingredient…
!
Topping
ingredient
ingredient
ingredient
ingredient…
Topping
/Steps
Steptechnique
technique/
Steps
step
METADATA:
HARISA,
CHILLI,
SAUGE,
ROCKET
METADATA:
GOATS’
CHEESE,
SWEET
PEPPER,
CHORIZO
METADATA:
ingredient
FETA,
ingredient
HUMUS,
ingredient
ZUCCHINI
ingredient…
/Ingredients
/Steps
Steptechnique
technique/
Steps
step
step
step…
/Steps
Reqtechnique
technique
technique/
/Preparation
/Recipe
What Is Structured Writing?
A
cooking
recipe
is
one
of
the
most
common
structures
Presentation
©
2013
Ray
Gallon
all
rights
reserved

4. HTML: Mix of Semantic and
Non Semantic Tagging
<dt class="stage-title">For the goats’ cheese, sweet pepper and chorizo topping</dt>
<dd>
<ul>
<li><p class="ingredient">50ml/1¾fl oz <a href="/food/passata" class="name food”>passata</a></p></li>
<li><p class="ingredient">50g/1¾oz peppadew peppers (these are available from most supermarkets, near the capers
and <a href="/food/vinegar" class="name food">vinegars</a>!)</p></li>
<li><p class="ingredient">3 sprigs of <a href="/food/thyme" class="name food">thyme</a> </p></li>
<li><p class="ingredient">1 <a href="/food/garlic" class="name food">garlic</a> clove</p></li>
<li><p class="ingredient">75g/3oz goats’ <a href="/food/cheese" class="name food">cheese</a></p></li>
<li><p class="ingredient">10 <a href="/food/chorizo" class="name food">chorizo</a> slices</p></li>
<li><p class="ingredient">extra virgin <a href="/food/olive_oil" class="name food">olive oil</a></p></li>
<li><p class="ingredient">small handful of fresh <a href="/food/basil" class="name food">basil</a> leaves</p></li>
<li><p class="ingredient">salt and <a href="/food/pepper" class="name food">pepper</a></p></li>
</ul>
</dd>
This
looks
mostly
like
XHTML,
and
is
mostly
semantic
(with
the
exception
of
the
<a>
tag
,
which
is
a
catch-­‐all
for
almost
anything).
Tags
like
<b>
or
<i>
however,
are
not
at
all
semantic.
Presentation
©
2013
Ray
Gallon
all
rights
reserved

5. XML: Purely Semantic Tagging
<task><title>Pizza Expressed Three Ways</title>
<taskbody>
<context>
…
<ul><title>For the goats’ cheese, sweet pepper and chorizo topping</title>
<li> <itemgroup props="ingredient">50ml/1¾fl oz <xref href="/food/passata" format="html" scope=“internal"
props=“name food”>passata </xref> </itemgroup> </li>
<li> <itemgroup props="ingredient">50g/1¾oz peppadew peppers (these are available from most supermarkets,
near the capers and <xref href="/food/vinegar" format="html" scope=“internal" props=“name food”>vinegars!) </
xref> </itemgroup> </li>
…
<li> <itemgroup props="ingredient">salt and <xref href="/food/pepper" format="html" scope=“internal"
props=“name food”></itemgroup> </li></ul>
</context>
…
Presentation
©
2013
Ray
Gallon
all
rights
reserved

6. XML: Purely Semantic Tagging
…
<li> <itemgroup props="ingredient">salt and <xref href="/food/pepper" format="html" scope=“internal" props=“name
food”></itemgroup> </li></ul>
</context>
<steps>
<step><cmd>Preheat the oven to 240C/475F/Gas 9.</cmd></step>
<step><cmd>Put the flour, yeast and salt into a large bowl and stir to combine. Make a well in the centre and add the
oil and 175ml/6fl oz of warm (but not too hot) tap water. Then mix it all together with a wooden spoon to form a
slightly sticky ball.</cmd></step>
…
<step><cmd>Once cooked, scatter the rocket over the harissa, chilli and sausage pizza. Scatter the basil leaves over the
cooked goats’ cheese pizza and drizzle with a little oil. Drizzle the balsamic glaze over the feta pizza with a good
drizzle of olive oil, then scatter over the mint leaves. Serve the pizzas immediately.</cmd></step>
</steps>
</taskbody>
Alternative
Semantic
Structure:
</task>
<step><cmd>Put the flour, yeast and salt into a
large bowl and stir to combine. Make a well in the
centre and add the oil and 175ml/6fl oz of warm
(but not too hot) tap water. Then mix it all together
with a wooden spoon.</cmd>
<stepresult>It will form a slightly sticky ball.
…
</stepresult></step>
Presentation
©
2013
Ray
Gallon
all
rights
reserved

7. Structuring Tools
Implemented
in
1980s
to
answer
needs
arising
from
paper-­‐to-­‐
digital-­‐media
transition,
adopted
as
ISO
standard
Uses
Document
Type
Definitions
(DTDs)
to
describe
the
logical
structure
of
document
Too
rich,
too
complex
to
be
really
useful
at
large
scale.
Favoured
largely
by
the
military.
Subset
of
SGML
Includes
output
specifications,
absent
from
SGML
Uses
DTD
or
Schema
languages
to
describe
the
logical
structure
of
document
Uses
a
terse
formal
syntax
that
declares:
Precisely
which
elements
and
references
may
appear
Where
in
the
document
of
the
particular
type,
and
What
the
elements’
contents
and
attributes
are.
A
DTD
can
also
declare
entities
that
may
be
used
in
the
instance
document.
Provide
much
greater
specificity
than
DTD
They
Namespace
aware
Provide
support
for
types
Presentation
©
2013
Ray
Gallon
all
rights
reserved

8. Some Specific Structures
e
r
th tion
fo
ion
roduc
at
cific
and
p ions,
e
d
at
L
sp ment
blic n,
use
XM ure
pu
roc hnical
aviatio ations
p
c
c
f
te ed
for y
appli
o
ign
av
des rts-­‐he
a
in
p
E-­‐learn
in
specifi g
software
ca
learnin tion
that
al
lo
g
speak
content
an ws
to
d
that
re
each
other systems
to
in
c
of
lear ords
and
tra
a
manner
n
ck
not
ne ing
experien s
all
types
cessar
ces.
LM
y
S
Dev
e
sch loped
e
b
man ma
for y
IBM,
t
o
age
d
by echnica pen
so
u
Oa
sis
f l
docum rce
oun
dat ents,
ion
Open
so
sourc urce
sche
ed
m
instru
repair
&
a
for
crow
m
ct
d
iFixit. ions
on
lin aintenance -­‐
co
e,
Foun m
now
m
develope
datio
anage
d
n
d
by
O
by
asis
cument”
-­‐
t
Definition
Do
“Elemen
eMaker),
oprietary
(Fram
Adobe
Pr
SGML
exportable
to
or
ions
f
cat
pecifi .
It
of
s
ction
e-­‐learning ns
Colle ased
tio
-­‐b
unica ontent
web s
comm de
c
e
si
LMS
defin en
client
.
Needs
m
e
betw ost
syste
h
and
a
Com
p
origi lex,
Flex
n
i
DTD ally
an
S ble,
now
G
in
X ML
ML
Presentation
©
2013
Ray
Gallon
all
rights
reserved

9. Managing Structure
EDITING
TOOL
AUTHORING
WEB
CMS
AUTHORING
VERSION
CONTROL
ASSET
MANAGEMENT
PUBLISHING
COMPONENT
CMS
VERSION
CONTROL
PUBLICATION
SNAPSHOTS
CORRELATION
OF
LANGUAGE
VERSIONS
BUILD
TIME
VARIABLES
PUBLICATION
SCRIPTS
DIGITAL
ASSET
MANAGEMENT,
DATABASE,
LMS,
ETC.
PUBLICATION
ENGINE
USERS
ACCESS
Presentation
©
2013
Ray
Gallon
all
rights
reserved

10. Not All CMS’s Are Alike
Web
CMS
Manages
documents,
might
manage
chunks
Component
CMS
Designed
to
manage
chunks
Oriented
towards
publishing
Works
on
authoring
side
only
Authoring
tools
included,
often
difficult
to
use
Integrates
with
specialised
authoring
tools
Works
authoring
side
and
access
side
Can
be
aware
of
specific
schemas
Some
Web
CMS’s
are
now
getting
more
structure
friendly
Presentation
©
2013
Ray
Gallon
all
rights
reserved

11. It Will Change Even More
CCMS
Web
CMS
Bug
Reporting
in-­‐ Mo
ap
p,
bile:
ad
ap embe
tiv
e,
dded
hig
h-­‐t ,
ou
ch
Content
Server
CRM
DMS
Metadata
Presentation
©
2013
Ray
Gallon
all
rights
reserved

12. What About the Writers?
ormation:
f
ey
write
in
ments
–
th
write
docu
t
no
longer
Writers
lf-­‐sufficien
readable
st
be
se
u
d
in
chunks
-­‐
m
assemble
e
be
Standalon
o
they
can
le
s
herent
sty
a
co
adhere
to
Must
fashion
Wr
ite
rs
ca
n
b
ec
om
e
S
ce
or
layout
’t
do
appearan
Writers
don
y
don’t
know)
e
ultichannel
-­‐
th
n
be
m
(publishing
ca
ME
’s
New
fun
ction:
co
ntent
ar
delivera
chitect,
bles
and
assemb
control
les
s
display
(via
CSS
)
Presentation
©
2013
Ray
Gallon
all
rights
reserved

13. Structure is Good - But
You Don’t Always Need It!
Conditions
when
you
don’t
need
structured
writing:
You
have
little
or
no
reusable
content
Desktop
publishing
(look,
layout,
precision
control
of
elements)
is
more
important
than
the
content
itself
You
publish
only
to
one
or
two
media
consistently
(especially
print),
and
mobile
devices
are
not
among
them
Unstructured
legacy
content
does
not
need
to
be
migrated
if
it
will
not
be
updated
-­‐
there
is
no
benefit.
Presentation
©
2013
Ray
Gallon
all
rights
reserved

14. The Big Mistake Not to Make
Never
start
a
migration
to
structure
before
you
understand
clearly
what
your
model
needs
to
be.
You
can
correct
many
errors
later,
but
the
model
must
be
right
from
the
start
-­‐
though
you
can,
of
course,
improve
it.
Tools
are
important
-­‐
even
very
important
-­‐
but
they
are
no
substitute
for
understanding
your
content.
A
Tale
of
Two
Migrations
Presentation
©
2013
Ray
Gallon
all
rights
reserved

15. Example: Enhanced Tool Tip
The
<shortdesc>
is
what
pops
up
on
hover
(Level
1)
The
<abbreviated-­‐form>
glossary
entry
is
resolved
without
popup
definition
in
the
tool
tip.
It
is
rendered
differently
in
the
task
topic.
This
is
managed
from
the
CSS
The
<resourceid>
element
links
the
tool
tip
to
the
interface
element.
ID’s
managed
by
the
development
team
with
tech
comm
input.
!
The
topic
body
and
link
are
shown
in
the
tool
tip
slideout
(Level
2)
Presentation
©
22013
Ray
Gallon
all
ights
reserved
Presentation
©
012
Ray
Gallon
all
rrights
reserved

16. Process Query Task Topic
The
<shortdesc>
and
first
<p>
are
reused
from
the
tool
tip
…to
pop
up
a
<keyref>
that
points
to
a
glossary
entry
!
This
time
the
abbreviated-­‐
form
is
resolved
on
hover…
Presentation
©
22013
Ray
Gallon
all
ights
reserved
Presentation
©
012
Ray
Gallon
all
rrights
reserved

17. Another Approach
Thanks to Nathalie Laroche and Ixiasoft
Tool
Tip
Level
1
Presentation
©
22013
Ray
Gallon
all
ights
reserved
Presentation
©
012
Ray
Gallon
all
rrights
reserved

18. Another Approach
Thanks to Nathalie Laroche and Ixiasoft
Tool
Tip
Level
2
Presentation
©
22013
Ray
Gallon
all
ights
reserved
Presentation
©
012
Ray
Gallon
all
rrights
reserved

19. Code Comparison of the
Two solutions
Tool
Tip
Level
1
Tool
Tip
Level
2
Related
Links
!
VALIDIT
IXIASOFT
Presentation
©
22013
Ray
Gallon
all
ights
reserved
Presentation
©
012
Ray
Gallon
all
rrights
reserved

20. RAY
GALLON
THE
TRAN
SFOR
C U LT U R E C O M
MAT
ION
S
O CI
ETY
Thank
You!
Check
out
my
blog,
Rant
of
a
Humanist
Nerd:
http://humanistnerd.culturecom.net
Email:
infodesign@culturecom.net
Google
Plus:
+Ray
Gallon
Twitter:
@RayGallon
LinkedIn:
Ray
Gallon
Member, Board of Directors
Presentation
©
2013
Ray
Gallon
all
rights
reserved