structured writing - what's it good for?
DESCRIPTION
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.TRANSCRIPT
RAY GALLONC U L T U R E C O M
Presentation © 2013 Ray Gallon all rights reserved
STRUCTURED WRITINGWhat’s It Good For?
THE TRANS
FORMATION
SOCIETY
Presentation © 2013 Ray Gallon all rights reserved
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
What Is Structured Writing?A cooking recipe is one of the most common structures
HTTP://WWW.BBC.CO.UK/FOOD/RECIPES/PIZZA_EXPRESSED_THREE_77124
Recipe !Video !Ingredients Pizza dough
ingredient ingredient…
Topping ingredient ingredient… !
Topping ingredient ingredient ingredient ingredient…
Topping ingredient ingredient ingredient ingredient…
/Ingredients
METADATA: HARISA, CHILLI, SAUGE, ROCKET
METADATA: GOATS’ CHEESE, SWEET PEPPER, CHORIZO
METADATA: FETA, HUMUS, ZUCCHINI
Preparation Steps
step step step
/Steps Steptechnique
technique/
Steps step
/Steps Steptechnique
technique/
Steps step step step…
/Steps Reqtechnique
technique technique/
/Preparation /Recipe
Presentation © 2013 Ray Gallon all rights reserved
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
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
… <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> </task>
XML: Purely Semantic Tagging
Alternative Semantic Structure: <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
Structuring ToolsImplemented 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
Some Specific Structures
Complex, Flexible, originally an SGML DTD now in XML
“Element Definition Document” -‐
Adobe Proprietary (FrameMaker),
exportable to SGML
Developed by IBM, open source
schema for technical documents,
managed by Oasis foundation
Open source schema for crowd-‐
sourced repair & maintenance
instructions on line, developed by
iFixit.com now managed by Oasis
Foundation
XML specifi
cation for
the
procurem
ent and p
roduction
of techni
cal public
ations,
designed
for avia
tion, use
d
in parts-‐h
eavy app
lications
Collection o
f specificatio
ns for
web-‐based e-‐le
arning. It
defines com
munications
between client si
de content
and a host s
ystem. Need
s LMS
E-‐learning software specification that allows learning content and systems to
speak to each other in a manner
that records and tracks all types
of learning experiences. LMS not necessary
Presentation © 2013 Ray Gallon all rights reserved
AUTHORING VERSION CONTROL
ASSET MANAGEMENT PUBLISHING
Managing Structure
EDITING TOOL
VERSION CONTROL PUBLICATION SNAPSHOTS
CORRELATION OF LANGUAGE VERSIONS BUILD TIME VARIABLES PUBLICATION SCRIPTS
COMPONENT CMS
PUBLICATION ENGINE
USERS
DIGITAL ASSET MANAGEMENT,
DATABASE, LMS, ETC.
WEB CMSAUTHORING
ACCESS
Presentation © 2013 Ray Gallon all rights reserved
Not All CMS’s Are Alike
Web CMS
Manages documents, might manage chunks
Oriented towards publishing
Authoring tools included, often difficult to use
Works authoring side and access side
Component CMS
Designed to manage chunks
Works on authoring side only
Integrates with specialised authoring tools
Can be aware of specific schemas
Some Web CMS’s are now getting more structure friendly
Presentation © 2013 Ray Gallon all rights reserved
It Will Change Even More
Content Server
CCMS
Metadata
Bug Reporting
CRM DMS
Web CMS
Mobile: embedded,
in-‐app, adaptive, high-‐touch
Presentation © 2013 Ray Gallon all rights reserved
What About the Writers?
Writers no longer write documents – they w
rite information:
Standalone chunks -‐ must be self-‐su
fficient
Must adhere to a coherent s
tyle so they can be assem
bled in readable
fashion
Writers don’t do appearance or layou
t
(publishing can be multichannel -‐ they
don’t know)
New function: content architect, assembles
deliverables and controls display (via CSS)
Writers can become SME’s
Presentation © 2013 Ray Gallon all rights reserved
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
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 reservedPresentation © 2012 Ray Gallon all rights reserved
!
Example: Enhanced Tool TipThe <shortdesc> is what pops
up on hover (Level 1)
The topic body and link are shown in the tool tip slideout (Level 2)
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.
Presentation © 2013 Ray Gallon all rights reservedPresentation © 2012 Ray Gallon all rights reserved
!
Process Query Task Topic
This time the abbreviated-‐form is resolved on hover…
…to pop up a <keyref> that points to a glossary entry
The <shortdesc> and first <p> are reused from the tool tip
Presentation © 2013 Ray Gallon all rights reservedPresentation © 2012 Ray Gallon all rights reserved
Another Approach Thanks to Nathalie Laroche and Ixiasoft
Tool Tip Level 1
Presentation © 2013 Ray Gallon all rights reservedPresentation © 2012 Ray Gallon all rights reserved
Another Approach Thanks to Nathalie Laroche and Ixiasoft
Tool Tip Level 2
Presentation © 2013 Ray Gallon all rights reservedPresentation © 2012 Ray Gallon all rights reserved
Code Comparison of the Two solutions
!
Tool Tip Level 1
Tool Tip Level 2
Related Links
IXIASOFTVALIDIT
Presentation © 2013 Ray Gallon all rights reserved
Thank You!
RAY GALLONC U L T U R E C O M
Email: [email protected]
Google Plus: +Ray Gallon Twitter: @RayGallon LinkedIn: Ray Gallon
Check out my blog, Rant of a Humanist Nerd:http://humanistnerd.culturecom.net
THE TRANSFORMATION SOCIETY
Member, Board of Directors