Transcript of our podcast episode Topic-based writing: what is it, and why should I care?

Below is a transcript of our podcast episode Topic-based writing: what is it, and why should I care? :

Hello and welcome to the Cherryleaf Podcast. In this episode we’re going to look at topic-based authoring.

This episode follows on from the recording about structured authoring, and also the one that we did on DITA. And topic-based authoring is a major part of technical writing. At the TCUK 2017 conference, there were four presentations and a workshop on topic-based authoring.

And we cover it in a number of our courses: in our advanced course on technical writing, in our induction course on technical writing, and to an extent in our course on writing policies and procedures.

Yet it can be hard for people outside of the profession people who aren’t technical authors to understand what topic-based or topic-based writing is.

So that’s what we’ll cover in this episode. So we’re going to look at what a topic is, look at single sourcing. And its relationship to topic-based writing.  And also multichannel publishing, the features of topics, why you’d want to take this approach. And also some of the reasons why you wouldn’t necessarily want to take this approach, where it can be applied. We’ll take a brief look at a situation where a company decided not to take this approach. That company being Microsoft. Some of the challenges around topic-based writing, some of the tools that you can use for topic-based writing, some important aspects that you need to know if you want to take this path. And how it can affect the other people within the publishing process.

But before we do that I’d like to talk about the future of this podcast. In many ways the topics that we choose are decided by you. We look at the statistics on which topics are the most popular. And that helps us know what we should do into the future. But we’d like to get you more involved in this podcast. And so we’ve set up a system and added a page on our website where you can push a button and record a message. So you can tell us what topics you’d like us to cover. You can also ask us questions. And we can address those into the future. And you can share your opinion and give your feedback on some of the topics that we’ve talked about in the past. So if you’d like to get involved and share your thoughts and opinions, take a look at the show notes. There’ll be a link to that space where you can record your messages, suggest some topics for future podcast episodes, ask questions that you’d like answered. They’ll be in the show notes, so please make use of that and to get involved.

So let’s look at topic-based authoring. The usual way in which a technical author might look to explain what topics are and topic-based authoring, would be to use an analogy based around Lego. That’s usually the most common one that you see within articles and even presentations. And the reasons for that are that with a piece of Lego you have a standardized unit. And you put different units together to build something. That you have a brick and you can use it to build a car. We can use the same brick to build a spaceship. And that analogy is useful in that topic-based writing is about self-contained units.

These self-contained units tend to focus on answering one specific question. They focus on specific topic. And they’re standalone. They’re modular. They can be moved to somewhere else. And they’re not reliant on something else. They’re not relying on you having read the paragraph before. So in that way it is a good analogy.

However, one of the features of topics are that they can be reused in more than one place. Effectively they can be in two places at the same time. And that isn’t really the case with Lego. The pieces are either in one construction or another. And this concept of having something that can appear in more than one place is something that is unusual. It is something that people are unfamiliar with. Physicists might understand it because it is something that electrons can do, but for many people it’s not something that they’re familiar with, not something that they’ve seen before.

Except in one situation. And that is where they have used a spreadsheets. People use spreadsheets for creating budgets for doing accounts. And in the days before spreadsheets it was done on paper. And if you for example sold something you would write down that sale in one ledger about what you’d solve that particular day. And you’d have to write down the same piece of information if it was being sold on credit into the sales ledger. So that you could see that that person owed you payment for that within say 7 days or 30, it would have to be recorded in the cash book that the money that came in for that particular day had come from the sale of that item.

And so it was a very time-consuming task of writing down in lots of different places the consequences of selling one item to a person. With spreadsheets you can have a cell with a value it can be the price of a widget. And then we can use that cell. And have it appear in different places within the spreadsheet. We can include it in formulas. So if somebody buys five widgets, we can have a form that says five times the price from that cell. And that gets the value of third item. So if the price changes we only need to change it in that one cell.

And the consequence of that change in that price gets rippled through all the formulas that use that item. And all the situations where that’s been listed at different places within the spreadsheet that sell that price for that widgets can be in many places. And because it’s in a spreadsheet, because it’s done in that way, if there’s a change we don’t have to be like the people with the paper ledgers. And make a change in one ledger make a change in another ledger. And so on we can change it in one place. And that ripples through.

And again with spreadsheets, what we can do is we can use pivot tables to look at information one way. And then flip it. And look at it in a completely different way.

And topics are like that that. You have a single place that you keep information. And then it can be referenced. And embedded or applied in lots of other places. And like with the spreadsheets, when it comes to making a change you only have to change it in one place so we’re moving into implicitly something that’s related to topic-based authoring. And if you do listen to presentations at conferences they often treat topic-based writing and single sourcing as one and the same thing.

This definition comes from Mike Hamilton who is one of the directors at MadCap Software, manufacturers of a Help authoring tool called Flare:

“It’s a documentation workflow where any piece of content exists only once content assembly is efficient. And controlled with flexible delivery to the end user that really in my mind is kind of an umbrella that all single sourcing topic-based authoring can live under.”

So let’s look at single sourcing. Single sourcing in the sense that it’s used within the technical writing world is to write a piece of text. And have it be able to be reused in more than one place like that cell within the spreadsheet. So that can be across different documents. So we can have a warning sign “do not do this”. And we can write that once. And we can have that topic appear at different situations where you might need to be aware of that warning within a document or across different documents.

You might have a document for end-users. You might have a document for partners who were then add their own brand in to. You might have a version 1 and a version 2.  And that same warning needs to appear in both those different versions.

So by a single sourcing you can write the content once in one topic. And it will appear in those different situations. And if it needs to change you change in the source topic. And then generally republish. That change will ripple through to all these different versions.

So single sourcing is a document workflow where any piece of content exists only once. And the way in which content is assembled and published. It’s done efficiently. And in a controlled manner.

And it means we’ve got flexibility on what we deliver to end users. So with all these different versions that we have for version 1 and version 2 for audience one, audience two.

We’re not writing those bits of information separately. We’re writing them once but saving it in different formats or publishing it in different versions.

Linked with this idea of topic-based authoring is how we manage variations. So there might be a feature within version 1  that’s not in version 2. There might be a specific situation for one audience but not for the other.

So if we’re talking about an audience based in London the phone numbers. And contact details might be different from the audiences based in the USA. One of the other things that we can do with a topic-based writing is within our topic we can mark-up text. And say applies to different situations or it applies to different audiences within our topic. We can have the phone number for London and mark that up as relevant for the London audience.

And we can mark up the contact details for America. And again identify that as relevant for the US audience. And so related to this idea of topic-based authoring is when the content is published, is the ability to hide, filter, reveal text depending on the different audience or circumstance.

So that we can say when it’s published the information for London will appear but the information for New York will be hidden or vice versa.

Alternatively we can have that information in topics. And we can use metadata information about the topic to do a similar thing if we don’t want that information actually written within the topic.

So we talked about single sourcing. And the way in which we can have one piece of content in different documents. What we can also do is something called multichannel publishing.

So as well as it being in different documents, it can be published in different mediums. So we can publish a topic as a webpage or part of a webpage we can publish a topic, on paper, in a PDF, embedded in their application, as a warning within a dialog screen. Within a single sourcing environment.

And typically with topic-based all three there’s a separation between how all the content looks and feels. And the words that have been written the way that the content appears is controlled in a separate area. It’s not defined within the topic itself.

Let’s look at the features that you would see in a topic. In many situations, each topic is a separate file. So they’re like little records in a card index that can be reorganized or used or combined to create documents. But it doesn’t have to be that way. You do have situations in some applications where the topics are stored in a database. And because you have an individual topic, it doesn’t necessarily mean that the page that the end user sees just has that one topic on it.

In many situations when it comes to publishing you take a set of topics. And you decide that those will go on one page. And a different set of topics will go on another page. And equally in a web environment as a web page you can have a collection of different topics that make up a whole page.

The topics tend to be short. And they should have what you might call an identifiable purpose they should be answering a single question if you find the topic answers to questions then it probably is the case that that topic should be split into two.

So that you have one topic for one question one topic for the other. In the previous podcast episode on structured writing we talked about XML. And again in many situations, topics do follow a structured authoring format. They are XML based. But it doesn’t have to be the case if you want to single source and reuse a topic in more than one place.

In addition to a topic, having one identifiable purpose, it should be one form of information type. And information types is something again we covered presentation on structured authoring. And also in the DITA episode.

So topics tend to be standalone. And one of the effects of that is that you can move them to a different place in the document. And it doesn’t break the document a topic doesn’t rely on another topic preceding it. And it can be single. Sourced it can be reused in different places.

And in most cases what’s happening is haven written these topics, to get it to be something that somebody reads, there’s another stage. A second stage, which is publishing or transformation, where these topics are converted into the output that the person will actually read.

They can be created by a list that’s created for publishing or in some situations, in some tools, you can embed one topic within another. So it’s different from a template in Word. It’s not copy and paste, and that’s it. And it’s not like snippets in Word either. If you change the content in the topic, then when it comes to the publishing stage, that change will be reflected in the outputs that are created.

And topics can be reusable. So they can be used for different customer journeys, different documents.

Why would we use topics? One reason is for certain types of documents, a topic-based approach with standalone units of information is better than the linear writing approach, the essay writing approach.

With an essay writing approach, it expects you to read the whole of the document from beginning to end it transitions from one to the other, “as I mentioned earlier”, that type of phraseology.

And in many situations, people don’t want to read the whole document from beginning to end. They just want to focus in on a particular section, find the important piece that they want, read it, follow its instructions.

If it’s instructional, get out get on with doing their jobs.

Another reason is that often in a business situation content is duplicated. If you have a warning, that warning might appear in the online version, that warning might appear in the paper version, that warning might appear in version. And a version for the Irish version. And the American version for the British version. And it can be that around 20% percent or up to  30% percent of content, particularly in the technical writing situation can be repeated.

And so by writing it once and being able to reuse it in many situations, you can save yourself time. And you can start to treat content as an asset get it to work a little bit harder. And where you have this repeated content just reuse it without having to copy and paste that. Sometimes this is called multi-sourcing. And if there’s ever a situation of need to change the text, you just change it in one place.

We’ve covered this already, but you can repurpose that content in different contexts, for different users, for different products. This can be by adding into the topic different scenarios or situations that you might want to cover. And then having a mechanism by which that content is filtered out or setting rules by metadata. So that when it comes to publishing, it picks which topics it wants to bring in or doesn’t want to bring in.

By having one piece of information, you have a single source of truth. You have it in one place. Another consequence of having topic-based writing where you’re answering one question is it does focus your writing. What you have to do is answer that question. And there’s a consequence of that they can help you spot when you’re starting to write. And plan your information you’re going to create: the sections. Where you don’t actually know the answer to those questions, you don’t know what the intent. And purpose is of each topic. And. So it can help you focus and go away and find the answers to those questions.

So you tend to get a consistent document.

So we’ve said that topics are used to build up a larger publication. And in most systems, most tools that are topic-based, what this means is you can have one person writing one topic and at the same time somebody else writing a different topic.

So a topic-based writing approach can mean that you’re able to share out the writing. You can have people working on different sections at the same time. And also as each topic is completed, in some situations, it may be possible to actually review that topic as that one’s done. So rather than having to wait till the whole document is completed it may be possible in some situations to review as you go along. You don’t have to wait.

As a result of all this, topic-based authoring is the standard default way that technical authors write user manuals, online Help technical documentation, but it’s not used universally within organizations. And in some situations that’s for good reasons. We need to look at why wouldn’t we want to use a topic based approach.

The most common situation is that some communication within a business needs to be a narrative. It does need people to listen to the beginning the middle and the end. Things do transition from one to the other.

And we’ve made a couple of assumptions in this. We’ve assumed that content will be reused. That’s not always the case if you speak to. Some of the people at the Government Digital Service, GDS, they don’t reuse topics within the content that goes onto the Gov.UK website, because they found that there’s been very few situations in for them where content is the same can be reused.

And another assumption is that if you have content that can be reused, that people will discover it and will reuse it. That’s not always the case.

We use a another example if you consider your company logo it may be that you have just one image file “logo.png’ . And in theory everybody could use the same file in all of the documents that they use. They could reference that file for the website, for sales proposals, for PowerPoint presentations. And so on.

Now in many situations, what you’ll find if you go into an organization is the company logo files, if you look on the company server, they are everywhere. And that can be as a result of people not being aware that there’s a single source. And that content is siloed. That where the file is stored or where the topic is stored is in one system. And the other systems that people are using can’t get at that system or aren’t told that that exists.

So to really get value out of a topic to make it really available across an organization you may need to look at how you can have data that can be interchanged across different systems across different silos.

Some examples of where a narrative style is used what blogs are often a narrative approach conversations are novels, adverts.

And with this collection of different topics there’s a temptation to publish each individual topic as an individual webpage, if it’s going online. And this can lead to atomization of information. Individual pages with maybe just two sentences on it. And from a search engine perspective, Google really doesn’t like tiny topics it thinks they’re of low value.

And you might find yourself at risk if you’re publishing information on page that Google doesn’t index them, ignores them. And when people go to search on a search engine, they just don’t appear.

And if we think of single sourcing the ability to take a topic and reuse it in different situations is because the controls for how it will look, the look and feel, are done separately from the topic itself. And that means that you may not necessarily see at the moment that you were writing what the document the final document will look like that a separation of the look and feel from the content can cause some problems.

You may need skills to create style sheets that make the content look really nice. So writing topics can take practice at the beginning. It can be hard to get them right. It forces you to answer a question in each individual topic you might not know the answer. And that can be challenging for you.

As well that might make you feel a little bit uncomfortable, it can be hard to spot existing topics that say the same thing. Although there are tools that can tell you all this looks like a topic that’s already been written.

And as it’s a different style of writing, it may mean that you’ve got to get people to adapt the change.

They may need training if you’re moving to a tool that enables you to write a topics. That may mean, often does mean, that you’re moving away from Word. So there may be a requirement to train everybody in that authoring tool.

We mentioned a few places where you might not want to use a topic based approach. Let’s look at where we could use a topic-based approach. And essentially it’s the type of documents where content appears in more than one place, where you have that content repeated in different situations. And that’s content that has in it warnings, content that might have lists or sets of instructions, or notes that need to be in the more than one place.

Within a business context, that’s often user guides and online Help. It’s often training guides, there’s a lot of shared material between user guides.

And it can be support articles knowledge bases as well.

Another good candidate is policies and procedures. That you can have again the same warnings or the same facts or definitions appearing in more than one place. For example, what is defined by a level three type of pay grade, or a level four type of pay grade.

Some other situations where it isn’t really used that often today but are good candidates for topic based approaches: one is sales proposals. And many sales proposals have the same information in every one. You’ll have information about the company or you’ll have a CV of a person that’s going to be doing the work a description of a product. And there’s a danger that each sales person will have their own proposal that our own template. And therefore if something changes, if somebody’s CV changes, they won’t be aware of that particular change.

By having a topic based approach, and by having single sourcing, you can update somebody’s CV say from six years’ experience to seven years’ experience, if they reference in that topic into their proposals. And they can ensure they have the up-to-date, correct version.

You might have reports that are done every month or by different sectors field reports for example. That could be a good candidate.

Chatbots. Chatbots are answering individual questions and so each of the answers to those particular questions is a topic.

And related to training and related to sales, you have the situation or the question about PowerPoint slides. Often you have different people making presentations. And they’ll have the same slides in them they’ll have the company slide giving information about the company.

It hasn’t been easy to have a set of sourced slides that can be slotted into different presentations. And then when you update that source slide, that changed to be reflected in those people’s presentations, to do that type of thing you need to move away generally from PowerPoint or Keynote. And move towards more of a situation of presenting HTML which can be generated from a tool that supports single sourcing and topic-based authoring.

We talked about the benefits that you might get from taking this approach. We’ve talked about why you might not want to do it. We haven’t talked about so far are situations where if you don’t use it what could the consequence of that be?

What are the dangers by not doing it? One example of a company that decided to move away from a topic based approach was Microsoft when they launched Microsoft Vista which was quite a long time ago now. And they decided that rather than take a topic-based approach, they would have articles. They would use journalists to write articles instead of the traditional Help topics.

The result of this was, in many situations, the writers lost focus. They found it hard to get to the point and give the end users the information that they needed. And so there was a lot of information within the articles that was repeating itself or wasn’t relevant.

And as well as making it hard for the end users to understand, what they should be doing when they got stuck with Microsoft Vista, it also made it harder for the translators to translate the content. So it had an impact on not really meeting the purpose for which it was being written, which was to help users when they wanted the answers to their questions. It meant they were writing more than they needed to.

If you want to take a topic-based approach to your writing, what tools should you use? Well, let’s start with the most popular tool that there is for writing, Microsoft Word. You can write topics in Microsoft Word, you can have a heading for each of the topics that you want to do make sure that each heading is about answering one question. And have topics in that way down a single word dot toc or do see X file.

The downside of Word is that if we also want a topic-based writing to enable us to single source and to reuse those topics in other documents, it’s really not designed to do that. So in many situations word isn’t the appropriate tool. There’s the help authoring tools, tools like MadCap Flare and RoboHelp, you can write individual topics. And then you can create tables of contents with the topics that you want in the publications that are there.

Some tools work in a different way. And they enable you to embed topics within topics.

One that might surprise you is WordPress. There are plugins for WordPress where you can create blocks of text. And then when you’re writing your WordPress blog or your WordPress page,s you can then click on a button. So I want this content block in my page. And these are stored separately. And again if you change the text when the WordPress page is served to the end user that change will be reflected. So this is great for any piece of text that would repeat on more than one page.

Another tool that took this embedding approach was a tool called Author-it. And for technologies or tools that are based on DITA or Markdown, they tend to use a similar approach. Something called transclusion. Where you’ll say, I want to include this topic into my document into my other topic. And it will then, at generation, include that piece of information.

So if you want to implement a topic-based approach a single sourcing approach, in addition to identifying the tool that’s appropriate. And what else do you need to know? Well there can be a learning curve. It is a different style of writing. And you may need to allocate some time to create publishing templates. When they’re generated to look like you want them to look to be of the standard that you want. And you also need to know that this might impact on others involved with the writing process. People who were reviewing your content, people that might be contributing content, subject matter experts, developers, do they stick with Word or do you get them to use this new tool? Can they write in just a text file and you import this information into your system? So you need to consider who else is involved in the workflow or process of creating content and publishing content.

The best way to understand topic-based writing is to do it. And there are courses, low cost courses, that we provided that introduce topic-based writing. There are presentations at conferences that explain what topic-based writing is. So you can get the basic understanding of how to approach and start to write.

And the best thing to do is to give it a go, or take an existing document you have, see if you can break it up into discrete standalone topics. All the sentences that need to be moved are their paragraphs within headings that need to be split out. And have their own heading to demarcate the start of a new topic.

We’ve looked at how it relates to structured writing. We’ve looked at what is a topic. We’ve looked at its relationship with single sourcing and multichannel publishing. We’ve looked at the types of features that you see within topics. We’ve looked at why we might want to take this approach and some situations why it might not be the right way to go. We briefly looked at the type of documents that might benefit from a topic based approach and the consequence is if you don’t take a topic based approach. And the tools that you could use. And some of the other factors that you need to be aware of in deciding to move towards topic-based writing.

And I said at the beginning it can be tricky to understand. So I would remind you of this spreadsheet analogy. If you think of a cell within a spreadsheet or value that you are there. And the fact that can be used in a lots of different places. And different situations within a spreadsheet. Essentially that’s what we’re looking to do with texts.

I hope that answered your questions on topic-based writing.

If it didn’t then you can go to our website and you can leave us a message. You can ask us the questions we didn’t answer or if there were sections that weren’t clear, you can hit that record button. And record down what it was that you didn’t understand. And we’ll see if we can follow it up with another episode about this.

If there are topics that you want us to cover in future podcast episodes, leave us a message. And we’ll do our best to answer them you’ll find the show notes for this episode at cherryleaf.podbean.com plus the link to the other episodes that we have done since May.

If you’d like to contact us, you can email us info@cherryleaf.com, in addition to that record button. And if you’d like more information on Cherryleaf, the questionnaire we’re running at the moment, the services we provide, the training courses we offer, the recruitment service that we offer, you’ll find all of that at www.cherryleaf.com. So finally I just like to say thank you for listening.

To record your questions and comments to the podcast team, use the green button on this web page: https://www.cherryleaf.com/useful-resources/podcast/