Below is a transcript of first half of our podcast episode What’s the deal about structured content? :
Welcome to the Cherryleaf podcast. It’s February 2018, and I’m off to the London Content Strategy Meetup, where we’ll be talking about structured writing. [Rahel Bailie] I thank our sponsors Syzergy and Scroll for doing this and I want to introduce her speaker this evening who’s Ellis Pratt. I know now Ellis for many many, many years, and he’s been incredibly kind to me since. I’ll tell you the Christmas story, the famous Christmas story later. He runs Cherryleaf, and I’ll let him tell you a little bit about that side. I have a handout for the best tweet, so you can use #ContentLDN as your hashtag and we’ll will begin.
When Rahel asked me, would I want to talk about structured writing, in some ways my first thought was to gulp, because this is a huge topic.
And then I thought about it, and thought, well, let’s go back to absolute basics and beginnings with the fundamentals of structured writing, structured authoring, and go from there.
So there are seven parts to this.
• A little bit about me and some questions about yourselves.
• The starting point. Actually, going back in time.
• And then coming up with a definition of what is structured writing, because if I described what structured writing is first, it won’t make any sense. It’s easier to give some examples and then from there assess what it is.
• Then how that definition of structured writing has changed as technology has come on board more in recent times.
• Different standards for doing structured writing
• Some of the issues if you do move, when you are using structured writing.
• And finally some future trends
So my background is in technical writing, writing instructional content, Help for applications, particularly software applications. I co-own a company called Cherryleaf. We’re based in Brighton and near Heathrow, and most of our customers are software companies. Another side we get involved with is policies and procedures to a range of more corporate companies.
I’m on the Council for something called the Institute of Scientific and Technical Communicators. That’s essentially the professional body for people involved with content writing and content strategy, technical writing. If you want to be part of a professional body to promote awareness of content, the importance of it … that’s really the body that’s around in the UK for that purpose. So it’s well worth having a look at and participating in. They have a great conference around the autumn time.
But what about you?
Let’s take a temperature of the room.
How many of you do structured writing today? Two.
How many have heard of structured writing before? Five. OK.
Who’s not heard anything about structured writing? Doesn’t really know anything about it? One
Who can’t be bothered to put their hand out? There must be more, because that doesn’t add up. OK
Before we define what structured writing is, let’s go back in time. Let’s go back to the Cold War, the Space Age, 1959, and a company called the Hughes Fullerton Ground System Group, which is based was based in Fullerton in California.
And what they did was, they would develop and design these little black boxes, which are next the guy . And these went into the aircraft to make sure that the guided missiles landed in the right place. And being the Cold War, being the 1960s, lots of bids and tenders were coming into that team, wanting to do very technical specifications to get those black boxes into different machines, different equipment.
And they were getting about 40, I think it was about 40 proposals every year. That they’re having to write. And the challenges they had were these:
How could they get the proposals finished on time?
How could they get different people that had expertise that would need to go into these tenders work collaboratively?
How could the end results make sense, and be coherent?
And how do they keep the general quality of those?
Anyone come across those sort of issues as well?
[Audience] Every day
So they devised something called STOP: Sequential Thematic Organization of Proposals. Which is actually STOOP, but they called it STOP. And this was a method for writing a structured method writing. If you like, I can send you a link to a document on how these proposals are written.
Within this STOP method the idea was an alternative to the way to what they called a river raft of text. That the reader would be on this raft, and going down this whole river of text, trying to find the information they wanted, to check: did this company meet the criteria for what we want to purchase?
What they did was, they set out an outline or structure for how the proposals should be laid out. And there were different rules for one page, two page and four page documents. This is the two page one, which is about no more than ten thousand words. Every section would have a thesis at the beginning. For these larger ones, on the right there would be a schematic that explained the diagram of how things worked. Rather than have a narrative this river after text, they were self-contained sections or chapters. So this would be about one thing, and then the next page or the next collection of four pages would be about something completely different. So there was a structure and organization there.
Let’s move on about eight or nine years, to the 1960s. And there was an academic called Robert Horn who was at, I think, Columbia and MIT, and then moved over to California. And he did an analysis of business documentation. And what he looked at were their common themes in all the different types of documents that were written.
And what he managed to identify were that there were different types of information or what he called “information blocks” that are appearing in every set of documentation. He identified 40 content blocks, which accounted for 80% of the content that was around a business and specifically for technical documentation. And about 50% of business documentation, there was there were six. And the big six were what he called:
• Procedure, which is a set of steps or instructions.
• A process, which is what happens from beginning to end.
• Principle, which is the underlying rules why somebody should do something, which today we’d probably call a policy.
• A concept.
• A structure. So this is where you’ve got different parts. That something would break down to.
• And facts.
And he set out rules and guidance on the best way to present 40 different information blocks. But the main ones were these big six that were there.
Has anyone come across Information Mapping? Yes, Rahel has.
And he developed this into something called Information Mapping, commercialised it. And there was a company called Information Mapping that sells training courses to teach people how to write business documents, reports, policies and procedures, to this particular method.
So what is Information Mapping? This is roughly what it looks like.
You have standalone blocks of text, or Information Blocks, and there are rules. So if you’ve got a an “Action Required” Information Block ,there’s advice on the best way to write a block of text that where you want to tell somebody they should be doing something.
The general rules are no more than nine sentences in in each block. Also with the both of these, alongside these Information Types, are rules on how to layout these different blocks of text.
it’s an outline, an information map, and what Robert Horn was able to do was, he was able to predict that if you’re writing proposal, there are certain sections that will appear in every proposal you’re writing. In a user guide, there are certain chunks of information that will appear in every user guide.
So what you can do is, you can give somebody, a writer, that outline, that list, and say these are the bits you need to fill in. So that can get around writer’s block. And what it can also do is help the writer identify where “I know nothing about this particular section; that’s the bit I need to go away and find out the information that I need to actually complete this document to the quality that that’s needed”.
So this is done by training people, and then having experts, or super users, that act as gatekeepers to identify where people are not following the standard.
Does anyone do something similar to that today?
[Audience] Try to.
So how this is different from other ways is that, often, you will do outlining to plan or prepare documents , but what we don’t do is, we don’t make that outline explicit to the reader.
One of the features of these formats is you’ve got chunking – relevance – where you’re only talking about one thing in each particular chunk. But you’ve also got this labelling, which means that the reader sees the outline and the structure of the documents that you’ve used to write that particular document.
And it works. It worked for Hughes Corporation. And it did the job, in terms of giving you consistency, clarity, definitely a better clarity.
What else did I write? Getting over writer’s block, and labelling. Also making it easier for the reader to get a sense of information, know roughly where in the document to go, to scan and to read.
So there were two examples. Now let’s do what we normally do at the beginning of any presentation: actually define what we’re going to talk about. And that is, what is structured writing?
So we’ll start with this definition: Structured writing is content that conforms to structural and semantic rules to meet specific business requirements.
So from those examples, there were particular rules and particular information types, or semantic rules, on how information was presented.
So it’s constrained writing. You’re telling your writers that they can only do things in certain ways. And it’s also working on the basis that we can model information, model documents, come up with an optimal model of how to present things, and then use them.
It’s a model of the content journey or the user journey as they’ve read through the information.
A couple other examples you might have seen. Who has used the Haynes manual in the past? Oh, you’re too young for that. So you will not know what Haynes manual is. No, because they branded under a different name in Canada.
So Haynes manuals are designed for the home mechanic who wants to maintain and repair their own car. Designed by Sir John Haynes.
And they have different Haynes manuals for different cars, different manufacturers. What’s happened is that those manuals, as well as being used by members of the public, are also used in workshops, by mechanics as well. And one of the reasons for that is that in every Haynes manual, the first chapter is about the engine, the last chapter is about the electrics.
And what John Haynes did when he started writing the manuals back in the 50s and 60s and has continued, is he defined a structure for how every manual would work. So if you’re a mechanic and you’re working on a Triumph, and you need to know what to do with the engine, you know roughly where in the Haynes manual to go. If you’re next going to work on Mercedes, you know in the Haynes manual roughly where you go to find the answer. If you use the official manuals from Triumph or Ford or Mercedes, they all use completely different structures and layouts and ways to do it. So you’re unsure to find the information. One the advantages of the Haynes manuals is the predictability, particularly if you’re moving from one car to the next.
Now, another one which I’ll use, this I know Rahel uses as an example for structured writing, is recipes. And if you look at a recipe for anything, be in one magazine of another, they almost all follow pretty much the same structure and layout. They tend to have the ingredients at the beginning, the temperature of the oven, how long it needs to be cooking for, the steps on what to do.
Some of them might say, how many calories, but informally over time, what’s sort of developed, is an informal structure and layout for writing and laying out recipes.
What’s changed over time, of course, is technology has arrived. And we’ve had more changes with that. Rather than have different documents, where you would cut and paste them, and do that as the way, that you combined content collaboratively.
Now what we have to do is, we’ll write a piece of information in a word processor, or some of the form, and we’ll get content from somebody else. And we’ll have to bring the two together to make a single knowledge base or article or quotation. And I guess most of you work in that way? You get content from different people? Yep. So what we want to happen is for that to happen seamlessly. And also for that to happen automatically. So that we can get information is coming from lots of different sources and present it without a human being having to tweak it and fiddle with it and improve it in in different ways.
And taking it a bit further, what we want, or often what we want, is to have bits of information appear in more than one place. It might be across different media, but it might also be in different documents. And we may also want to manage variations in documents as well.
And in the world of technical writing, we also talk about intelligent documents and intelligent publishing. So it can be presented in different layouts, but also personalized content, so that we can make the information relevant to each individual user.
We see this with the rise of things like chatbots. So “find the cheapest hotel near to the airport that are leaving from on Monday”. That relies on the system knowing who you are, when you’re traveling, where you are, to make the filter that information be specific to your situation.
And we want to do that automatically.
And also, if we’re translating into different languages, if we can translate a piece of text once and reuse it lots of different places will save an awful lot of time and money. Than having one version of a piece, another version that’s slightly different that has to be translated. And in translation you’re paying X pounds per thousand words.
It can get very expensive. And a lot of the drive for structured writing has come from mainland Europe in many ways, because they’ve had this need to translate into more than more than one language.
So if we go back to our definition, we can tweak it slightly. This is a definition from a chap called Don Day. So we can add in a bit. So it’s still “content that conforms to structural and semantic rules”. What we can add in is “that allow us to have automatic machine processing to meet the goals of the users and the business”.
One example which we’ve come across in the past. It seems like policies and procedures in every company will have a fire safety procedure.
There’ll be a fire safety procedure for here, you might have an office in Dublin. The procedure for getting out the building between Dublin and London will be almost the same. But what will change is, the number that you dial to phone the Fire Brigades, where the fire escapes are, the names of the Fire Marshals, the name of the fire brigade.
And so you probably have eighty, ninety, percent of the content that’s common, then little bits that differ between London and Dublin. And in an ideal world, you can give Dublin specific Health and Safety, fire safety guide that’s relevant to their situation, and London a specific guide. But the core text of what you should do is managed centrally.
So if you change the policy from what to do: whether you get out and phone the fire brigade first, or you phone the fire brigade, then get out the building… that you only have to make that change in one place. And not have to manage one manual where the information is in Dublin, one manual in London, remember if you make a change in one that you’ve got a copy and paste it into the other.
That’s a one common in situation. Oh, and you may have different audiences. particularly policies and procedures.
So you have, often, a need for different filters into the same information. Particularly the world that I come from, with technical documentation. We have situations where there’ll be a free version of an application and a paid for version of an application. There’ll be a Version 1 and they’ll be a Version 2. We’ve just done a project where the version for Mac OS and the version for iOS differed in two different ways.
And you might have content that needs to be reused in the training material, for the support desk, and in the Help text. So structured writing and topics can help enormously in in those worlds.
Does anyone here knit? Anyone here heard of Ravelry? One person. You’ve heard of Ravelry.
Ravelry is the world’s largest network or website for people who knit and crochet. And there are lots and lots. Hundreds of thousands. Three hundred and thirty thousand, nine hundred and forty five knitting patterns and crochet patterns on that site.
And what Ravelry got their users to do, was to add a taxonomy, or metadata, to all of the patterns that are in the site.
So picking one at random. So they added this metadata: what needles you use, what type of yarn you need, how much yarn you need, level of difficulty, whether it’s knitting or whether it’s crochet…
So you can navigate by type of clothing, type of wool, type of knitting needle, level of difficulty all manner of different ways because they have divert this taxonomy or structure for these three hundred and thirty nine hundred and forty-five different patterns that are on there now.
When you get into actual, the knitting pattern itself, and the PDF of that pattern, there are variations of how they’re laid out differs. There doesn’t seem to be a structured writing standard for how knitting patterns are laid out. And they do seem to vary from manufacturers. But it’s the fascinating site to navigate around, even if, like me, you know absolutely nothing about knitting. Just to see all the different ways that they’ve made it possible to filter, navigate, and get to interrogate this information. In the different ways that you want.
Another big thing that’s on the horizon, well it’s here today really, is chatbots. Is anyone involved within AI and intelligent chatbots yet?
So we all know what chatbots are.
There’s two types of chatbots. One is, you predict what questions somebody would ask, and then you write an answer to them. And it appears, usually in a chat window, to give you the answer. The other way is that it uses machine learning. When somebody asks a question, it interrogates a body of knowledge, a corpus, finds the best answer, and then brings that up. And then, depending on whether the user says “yes, this answers my question” or not, it learns and over time. It improves the quality of the answers it gives.
To improve that service, the software that drives this uses a structure. It needs to know the intent of the user, what they want to achieve, what they’re talking about, what the entity is, and also who they are, where and when they’re asking this particular question.
And from the body of knowledge, what you need to do is mark up your text to say that this is relevant for somebody who’s in this location, in this context. This is relevant to somebody who wants to do this or that.
And so, very much, the push, where we see this growth in user agent chatbots will be to add a structure to our content. To improve the quality of the answers that we get from the system.
But we go back to what I mentioned earlier. About this goal of wanting to take content from two sources and bring them together. Does anyone ever had to do that with Word?
Who has had difficulties? Where you’ve got it in one set of styles and somebody else has done it in another?
Word is a many sides, a many functional thing. It’s part desktop publishing tool, as well as word processing tool. And it’s very easy within Word to break any rules in terms of styles and standards, colours and fonts. And it can be a nightmare if you’re getting content from other people and they don’t know how to use styles or headings in Word.
Does anyone get content in HTML or Markdown? Even with Markdown, which strips out the presentation from the text, you just have text and headings, it still can be a challenge. Because you might use a three level heading structure in your document, and the content that you get from your contributor might use four headings. Some of the work that we do is actually taking documents and applying consistent heading levels to them. Where some sections use five headings, some sections use three, and just make them more consistent in the levels that they go through.