Topic-based authoring: The undiscovered country

NT Live Hamlet Many software companies, when they start out, provide user documentation as downloadable PDFs or as web pages. As they develop more products and versions, and as they expand into countries that use different English spellings, the amount of documents can grow until it becomes hard to keep all of these documents up to date.

It’s at this point that they tend to call a specialist technical writing company (such as Cherryleaf) to see if they can fix the problem for them. We find they’ve usually had a brief look at a Help Authoring tool, such as Flare or RoboHelp, and can see that it would solve a lot of their problems. However, they’re often not really sure how to use these tools in the best way.

Although topic-based authoring has been around for over twenty years, for many people it’s a completely new concept. It is, to quote from either Hamlet or Star Trek VI, an undiscovered country. Our meetings with them often end up focusing on the benefits of topic-based authoring.

Topic-based writing is an approach where you write a piece of text (or topics) that typically contains a paragraph or two about a single topic. These topics can be combined to create a page in a PDF document, and they can be organised in a sequence to create an online Help system ( See topic-based authoring page in Wikipedia). It’s a modular approach to creating content. The main advantage of this approach is the topics are often reusable; you can save time by reusing topics across different documents, and you can publish the same content to different media. For example, you could use a topic in training courseware, in a user guide and in marketing information.

As each topic is usually about a specific subject, and has an identifiable purpose, it can also help the writer write more clearly. If you need longer articles, you can build these up from the topics you’ve created.

It’s easy for professional Technical Authors to forget sometimes that many people have never come across this approach to writing before.

Different world views of content and content strategy

TshirtThere’s a wonderful German word, die Weltanschauung, which roughly translates as a view of the world. It suggests there is a framework of ideas and beliefs behind people’s descriptions of various things in the world. I was reminded of Weltanschauung at this week’s London Agile Content Meetup, where Rahel Bailie neatly summed up some of the different views of content, content strategy and single sourcing.

Baked v Fried content

Paul hollywood

CMS Wiki described baked content as “pages that have been generated by a Content Management System, but then moved to a static delivery server, which can serve them at high speed and high volume”. The word “baked” is used, because this approach means you cannot separate the content from the format afterwards. They are baked together.

“Fried” content is where the Web pages are built “on the fly” when they are requested by the end user. Rahel used the example of frying eggs: if you put too many eggs into the frying pan, you can always remove one. Fried content may take a little longer to generate than baked content, but this approach enables you to personalise and filter the content. It also means you can present the information in different ways, depending on which device a person is using.

COPE through technology v COPE through authoring

COPE (Create Once, Publish Everywhere) is another way of describing single sourcing content.

“COPE through technology” is the view that the content is essentially data that can be managed through software. If you need to create a personalised or filtered view of the content, you get a developer to create that version. If you need to create a mobile-ready version of your site, again you get a developer to do this. Content is often created by completing forms, in order to create structured information.

“COPE through authoring” is  the view that the writers can do all of the fine-grain manipulation of content. If you need to create a personalised or filtered view of the content, you get the Technical Author to mark up sections for those different conditions in the content itself. To quote Rahel, “You can then run a transformation script run, which compiles the content into its final form, and uploads the content to the Web CMS, or other publishing platform, for consumption and presentation.” The advantage of this approach is it stops you from being tied to a technology or application. The disadvantage is it relies on your writers being able to mark up and structure the text correctly.

It’s important to be aware of these distinctions when you talk about content, content strategy and single sourcing, because your Weltanschauung may not be shared by the person you’re talking to.

See also: Introduction to Content Strategy Training – Classroom and Online Courses

A free illustrated guide to content strategy

One of the kind things people were saying to us at the tekom conference last week was they enjoyed reading our free illustrated guide to DITA. Indeed, we’ve been bowled over by the response to this mini graphic novel and the number of people who have downloaded it.

Download our free illustrated guide to content strategyThis prompted us to complete a second illustrated guide we had “in the works” – on content strategy.

Again, this guide takes the form of a graphic novel:

It’s free, 14 pages long, and it’s published under a creative commons licence. MOBI and EPUB versions will be available shortly.

Let us know what you think of it.

See also:

Changing times in technical communication 2 – Workflow

Science Museum/Science & Society Picture LibraryWe’ve been on the road in recent days and weeks, visiting different documentation teams, and we’ve found there are distinct signs of change. In this post, I’ll look at how we’re starting to see the workflow for creating User Assistance beginning to change.

We found many documentation teams overstretched and starting to be asked how they could create content for new products that were coming along. Some organisations have decided they can only deal with this extra workload if they rethink the workflow for how content is created.

Continue reading

Why your Web content is like Doctor Who

Doctor Who logoDoctor Who is a popular British TV science fiction series that is celebrating its 50th anniversary later this year. So why is it like your Web content? Let us explain.

Regeneration is a part of life

The many faces of Doctor Who - WikipediaOne of the reasons why Doctor Who has managed to be popular for so long is due to the ability of the Doctor to regenerate: if he is old or mortally wounded, he can transform into a new physical form with a slightly different personality.

Similarly, your content may need to take on different forms over time. You may need to change the way it looks to suit different devices, or modify its personality (the tone of voice).

The basic fundamental story, or content, probably doesn’t not need to change greatly, as its purpose is likely to stay the same. However, it’s important to recognise and accept changes to the presentation format are now a fact of life for your Web content.

The Doctor’s companion

Clara Oswin OswaldIn most Doctor Who stories, the Doctor has a companion who travels with him and shares his adventures. The companion asks questions, often gets into trouble, helps the Doctor, and on occasions, rescues or challenges the Doctor.

The companion shows the importance of explanation – acting as the surrogate audience, asking the questions they may have, giving them important information and providing a persona they can relate to.

The readers of your Web content may also need a companion – someone who can assist them, enable them to have their questions answered. In the world of technical communication, we call this “User Assistance” or “online Help”.

Even the Doctor, one of the most expert of people needs an assistant. There are many times when he is overconfident, makes the wrong assumption, and is helped out of his predicament by his companion. This is also true for your expert users.

The sonic screwdriver

Whenever the Doctor wants to learn about a new world, a new creature or machine, he whips out his trusty sonic screwdriver. It gives him data that helps him understand how to solve his current problem. We need our own sonic screwdriver for our Web content – ways to measure its performance (i.e. if it’s meeting the users’ requirements), discover where the problems lie, and so on.

The Tardis of content

Tardis at BBC TV centre

The Tardis, as nearly everyone knows, is bigger on the inside than it is on the outside.

Unfortunately, only the Doctor knows where everything is located, and we generally only see a glimpse of what’s inside. We know there’s a swimming pool and a library, but often people get lost within the Tardis and end up where back they began.  There’s no official map of the Tardis, as far as we know, and it seems like there’s no logical structure to the corridors and rooms.

This is often the case with your web content. There’s lots of information, but it can be hard to find. If you know it’s there, you can search for it, but often you need a person to guide you to it.

Access to the Tardis is generally limited to those the Doctor invites in (or to those who are given a key). Many organisations take the same attitude to their online Help content: they hide it away from public view and, as a consequence, prospective customers.

The Whovians

Doctor Who fans Flickr image by Jason RiedyWhovians is the name given to fans of Doctor Who. Doctor Who has a huge and passionate following, which means they, in a way, “own” Doctor Who has much as the BBC and its writers.

Today, Doctor Who is a “Second Screen” experience: as people watch the TV show, they also converse on Twitter and Tumblr. The user generated content is an important reason why Doctor Who is so popular today. This can be true for your website as well: your users are part owners of your site and its content; their user generated content can be as important as the content you provide.

What have we missed?

Let us know if we’ve missed out any other links between Doctor Who and your Web content.

(Doctor Who fans Flickr image by Jason Riedy)

New case study – Helping HCC deal with the size and complexity of embedded systems documentation

You’ll find a new case study on the Cherryleaf Web site: Helping HCC deal with the size and complexity of embedded systems documentation.

HCC Embedded is a high tech software corporation that develops specialist software for deeply embedded systems, such as file systems, USB and networking software.

HCC_logo

Dave Hughes, CEO of HCC, realised that with over 100 different modules to be documented, often with inter-dependent content and frequent updates, managing the documents in Microsoft Word had become unmanageable and untraceable.

HCC’s documentation assists users developing with the products, and it plays an important role in the marketing of HCC’s products to developers. This means keeping a consistent format and brand across all this material is critical to the organization.

For the rest of the case study, see Helping HCC deal with the size and complexity of embedded systems documentation.

Content Strategy Lightning Talks: Applying Lean principles to content strategy

On Tuesday 26 February, Ellis Pratt from Cherryleaf will be speaking at the popular London Content Strategy lightning talk.

Ellis will explain how the principles of Lean manufacturing can be applied to developing and managing content. It’s a way of writing that focuses on maximising the value to the user and minimising waste. Since the Agile development methodology is based on Lean principles, it will help you to position content management within an Agile environment.

Each speaker gets 5 minutes and 20 slides (15 seconds per slide) to share their unique perspectives on content strategy in a blur of energy, passion and intensity.

See Content Strategy Lightning Talks, 26th February