structured writing - what's it good for?

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


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.


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

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>50ml/1¾fl oz <a href="/food/passata" class="name food”>passata</a></li><li>50g/1¾oz peppadew peppers (these are available from most supermarkets, near the capers and <a href="/food/vinegar" class="name food">vinegars</a>!)</li> <li>3 sprigs of <a href="/food/thyme" class="name food">thyme</a> </li> <li>1 <a href="/food/garlic" class="name food">garlic</a> clove</li> <li>75g/3oz goats’ <a href="/food/cheese" class="name food">cheese</a></li> <li>10 <a href="/food/chorizo" class="name food">chorizo</a> slices</li> <li>extra virgin <a href="/food/olive_oil" class="name food">olive oil</a></li> <li>small handful of fresh <a href="/food/basil" class="name food">basil</a> leaves</li> <li>salt and <a href="/food/pepper" class="name food">pepper</a></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 or however, are not at all semantic.

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

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

…


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


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


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


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


It Will Change Even More

Content Server

CCMS

Metadata

Bug Reporting

CRM DMS

Web CMS

Mobile: embedded,

in-‐app, adaptive, high-‐touch


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


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.


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.

!

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 are reused from the tool tip


Another Approach Thanks to Nathalie Laroche and Ixiasoft

Tool Tip Level 1


Another Approach Thanks to Nathalie Laroche and Ixiasoft

Tool Tip Level 2


Code Comparison of the Two solutions

!

Tool Tip Level 1

Tool Tip Level 2

Related Links

IXIASOFTVALIDIT


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

structured writing - what's it good for?

Technology