What's the deal about structured content?technicalcommunicationuk.com/wp/wp-content/uploads/... ·...
Transcript of What's the deal about structured content?technicalcommunicationuk.com/wp/wp-content/uploads/... ·...
About me
Director at Cherryleaf, a technical writing services and training company in the UK
I’m also on the ISTC’s Management Council
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?
Proposals were organised into a consistent sequence of themes
The right page always showed a
graphic
The left page had to contain
explanatory text
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)
Information Mapping
Standalone “Information Blocks”
Conforming to rules on how to present the
Information Blocks
The result
Consistent documents of a high quality
Improved clarity
Improved findability
Less writer’s block
What is structured writing?
“Content that conforms to structural and semantic rules,
to meet specific business requirements.”
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
Product documentation
Pro and Lite version
Version 1 and Version 2
MacOS and iOS
Training, Help and Support content
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
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>
Orgs don’t want to do it
After 10 years, approximately only 9% of technical communicators use DITA 9%
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`
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.
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"}
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?
For more information
@ellispratt
© Cherryleaf 2018 Images and screenshots © their respective owners