What's the deal about

structured content?

Ellis Pratt @ellispratt

TCUK 2018

Overview

1.The Past

2.The Present

3.The Future

About me, About you

About me

Director at Cherryleaf, a technical writing services and training company in the UK

I’m also on the ISTC’s Management Council

About you

Who has experience of structured writing?

In the olden days

In 1959…

Hughes-Fullerton Ground Systems Group

They needed to write lots of proposals

How do we get the document finished on time?

How do we work collaboratively?

How do we maintain coherence?

How do we control quality?

They devised STOP

Sequential

Thematic

Organization of

Proposals

Proposals were organised into a consistent sequence of themes

The right page always showed a

graphic 

The left page had to contain

explanatory text 

The Sixties

1968

An academic called Robert Horn identified common types of information

that account for nearly all the content of business and technical communication

Six “Information Blocks”

Procedure A set of steps an individual performs to complete a single task

Process A series of events, stages or phases that occurs over time and has a specific outcome

Principle A statement designed to dictate, guide or require behavior

Concept A class or group of things that share a critical set of attributes

Structure A description or depiction of anything that has parts or boundaries

Fact A statement that is assumed to be true

(There are additional information blocks in Information Mapping)

Horn used this to develop the “Information Mapping” method

Information Mapping

Standalone “Information Blocks”

Conforming to rules on how to present the

Information Blocks

Common features

Common elements

1. Information Types (topics)

2. Information maps

Achieved by

Training all the writers in the method

Having editors to act as quality controllers

The result

Consistent documents of a high quality

Improved clarity

Improved findability

Less writer’s block

What is structured writing?

What is structured writing?

“Content that conforms to structural and semantic rules, 

to meet specific business requirements.”

What is structured writing?

Constrained writing

What is structured writing?

A (information) model of the content journey

More examples from the olden days

Haynes manuals

Recipes?

The rise of the machines

Combining content

We want

Automated processing of content

We want

Topic reuse (Transclusion)

To be able to manage variations

We also want

Intelligent styling of publications

Intelligent/personalised content

Efficient translation

So what is structured writing, again?

“Content that conforms to structural and semantic rules

that allow machine processing 

to meet specific business requirements.”

Don Day

Use Cases

Product documentation

Pro and Lite version

Version 1 and Version 2

MacOS and iOS

Training, Help and Support content

Intelligent chatbots

Relate our content (response) to:

Intents

Entities

User role and context

This is hard with Microsoft Word

It’s hard with Markdown and HTML, too

I use 3 Heading levels

You use 4 Heading levels

The different standards

Standards are like toothbrushes

Standards are like toothbrushes

Everyone wants to use their own,

not any one else’s.

Regulatory standards

S1000D/ATA100

MILSpec

S1000D

Modular content stored in a database

Originally designed for aircraft, but later modified for use with land, sea, and commercial equipment

S1000D Information mapsATA No. ATA Chapter name

ATA 00 GENERAL

ATA 01 MAINTENANCE POLICYATA 02 OPERATIONS

ATA 03 SUPPORTATA 04 AIRLINE USE Aircraft HandlingATA 05 TIME LIMITS/MAINTENANCE CHECKS

ATA 06 DIMENSIONS AND AREASATA 07 LIFTING, SHORING AND JACKING

ATA 08 LEVELING AND WEIGHING.ATA 09 TOWING AND TAXIATA 10 PARKING, MOORING, STORAGE AND RETURN TO SERVICE

ATA 11 PLACARDS AND MARKINGSATA 12 SERVICING - ROUTINE MAINTENANCE

ATA 14 HARDWARE AND GENERAL TOOLS

S1000D Information TypesCrew/Operator

Description

Procedural

Fault

Illustrated Parts Data

Schedules

Wiring

Process Module

Business Rules Exchange

DITA

Based on STOP, Information Mapping, and DocBook

Task topic example<task id="birdhousebuilding"> <title>Building a bird house</title> <shortdesc>Building a birdhouse is a perfect activity for adults to share with their children or grandchildren. It can be used to teach about birds, as well as the proper use of tools. </shortdesc> <taskbody> <context>Birdhouses provide safe locations for birds to build nests and raise their young. They also provide shelter during cold and rainy spells.</context> <prereq>To build a sound birdhouse, you will need a complete set of tools: <ul><li>hand saw</li> <li>hammer ... </li> </ul></prereq> <steps> <step><cmd>Lay out the dimensions for the birdhouse elements.</cmd></step> <step><cmd>Cut the elements to size.</cmd></step> <step><cmd>Drill a 1 1/2" diameter hole for the bird entrance on the front.</cmd> <info>You need to look at the drawing for the correct placement of the hole.</info></step> </steps> <result>You now have a beautiful new birdhouse!</result> <postreq>Now find a good place to mount it.</postreq> </taskbody> </task>

DITA Map example

<map> <title>DITA work at OASIS</title> <topicref href="oasis-dita-technical-committees.dita"> <topicref href="dita_technical_committee.dita"/> <topicref href="dita_adoption_technical_committee.dita"/> </topicref> <!-- Contents of the oasis-processes.ditamap file --> <topicref href="oasis-processes.dita"> <!-- ... --> </topicref> <!-- ... --> </map>

The problems

Semantic Markup

It’s strict and restrictive

It’s constrained writing

What about your existing content?

Do you convert it?

Orgs don’t want to do it

After 10 years, approximately only 9% of technical communicators use DITA 9%

Simplifying DITA

WYSIWYG editors

Simplifying DITA

Lightweight DITA

AsciiDoc semantic markup?

AsciiDoc is based on DocBook XML

:summary: Asciidoctor is a mature, plain-text document format for writing notes

= Reference DocumentationLead Developer

This is documentation for project X.

include::basics.adoc[]

include::installation.adoc[]

[.rolename]`monospace text`

The future?

Use forms?

Headings must be marked semantically

But the data must be more than plain text

SPFE

Promoted by Mark Baker (Every Page is Page One)

SPFE = Synthesis, Presentation, Formatting, Encoding

Use queries instead of maps

topic head identity tracking index  body topic-structures text-structures paragraphs mentions decorations

Use queries instead of maps

*[_type == ‘Windows’ && releaseVersion > 2.0]

You write a query expression that selects the topics to be included in a page based on their metadata.

Documentation as an API

aka “Headless CMS”

It provides the content as data over an API.

You then write one or more front-ends that present the content to end-users. 

A headless CMS

Query Response*[_type == 'movie' && releaseYear >= 1979]{ _id, title, releaseYear, "directorName": director->name}

{ _id: "alien", title: "Alien", releaseYear: "1979", directorName: "Ridley Scott"}

A Headless CMS

You then write one or more front-ends that present the content to end-users

Summary

Do we want?

Automated processing of content

Topic reuse

To be able to manage variations

Do we want?

Intelligent styling of publications

Intelligent/personalised content

Efficient translation

Do we face this?

How do we get the document finished on time?

How do we work collaboratively?

How do we maintain coherence?

How do we control quality?

Questions (I have laptop stickers to give away)

For more information

ellis@cherryleaf.com

@ellispratt

© Cherryleaf 2018 Images and screenshots © their respective owners