[Intro Music]
[Ryan Weber] Welcome to 10-Minute Tech Comm. This is Ryan Weber at the University of Alabama in Huntsville. I often find it challenging to explain topic-based authoring, so today I’ve brought in an expert who can help us with this concept.
[Jennifer Morse] My name is Jennifer Morse and I’m a product evangelist here at MadCap Software.
[Weber] Today I’ll talk with Jennifer about what topic-based authoring is and strategies that technical communicators can use to put it into practice.
[Begin Interview]
[Weber] Welcome to the podcast Jennifer. We really appreciate you talking with us today about topic-based authoring. And I guess to get started, if you can just define what topic-based authoring is?
[Morse] Sure. Well thanks so much Ryan. So, topic-based authoring is the approach of writing content in a granular modular format, and so this granular bit are simply called topics. So, a topic is simply a chunk of information about a particular subject. It generally has an identifiable purpose and is something that can stand on its own. And so if we compare this with a tool like maybe Microsoft Word or even Google Docs or FrameMaker, those are linear based authoring tools. So, you essentially start at the beginning of the document or the chapter and you write until the end. So, topic-based authoring, the way that works is it just gives authors the ability to work on much more granular content and I think want to point out that even though authoring and topics is a different approach than authoring in a linear fashion, it isn’t that different from how one may be used to using Microsoft Work or Frame. So, I’ll give you a quick example, so if you think of that long policy manual or that long procedure manual or that reference guide, let’s say it’s made up of six chapters. Well it already has six granularity points built into it but if we look at say chapter three, now chapter three maybe it has two procedures and two reference sections. That’s one more level of granularity and that’s really all we’re doing with the topic-based approach. We’re going to take those two procedures and those two reference sections that make up the entirety of chapter three and we’re going to break them out as standalone files and those standalone files are going to be topics. Now there’s no real rule as to how long a topic needs to be but as I mentioned above it should be something that has an identifiable purpose and it should be able to stand on its own. So, if I want to make a pdf policy and procedure manual that just includes those two procedures and those two reference topics, because that’s what my audience needs, then I simply grab those two topics and stick them together like little Legos and now I have a new document. They’re literally like little Lego bricks, so at the same time maybe I want to create a searchable and navigable internet site that just has procedures in it. Well then, I can grab all of my procedure topics and link them together and publish them in an online output rather than pdf, and maybe that lives on a company intranet or a webserver somewhere that’s protected. So, by modularizing our content like this, we’re not adding any extra work but we’re just adding more flexibility in how we can reuse this content in the future.
[Weber] So each of these topics in our-like you said they’re modules, those little chunks of information that are designed to stand alone is that right?
[Morse] That’s correct. That’s correct because if they’re-if they’re designed properly and if they are able to stand on their own without any other kind you know reference material to make them useful, we can reuse them much easier.
[Weber] And rearrange, you were talking about kind of putting them in different places or reordering them or putting different topics together based on audience.
[Morse] Exactly. Yeah it just becomes-we want to get to a place we’re sort of on a publish on demand type of system, which makes things really easy.
[Weber] Great, well you’ve already spoke into this a little bit, but how then does this process of topic-based authoring differ from your more conventional writing? Your you know sitting down and-.
[Morse] Sure.
[Weber] -putting the entire chapter in Word.
[Morse] Right, so I’ll kind of use Word as a quick comparison since most folks are familiar with that. The challenge with Microsoft Word is that the very things that make it so easy for us to use are the things that get in the way of content reuse. So that’s because when you’re working in Microsoft Word, you’re actually doing three things at once, and it’s interesting because it’s not something that we often think about because for most of us it’s become second nature. And what we’re doing is we’re writing all of our content but we’re also embedding all of the formatting of that content. What are the fonts look like? What’s our spacing? What are the colors? So, all of that’s getting put into the document and the last thing is we’re defining the overall scope of the document. And what do I mean by scope? Well if I’m writing a training manual in Microsoft Word, it’s always going to be a training manual. If I’m writing an installation guide in Microsoft Word or in Google Docs, it’s always going to be an installation guide. So essentially what that document is gets baked right in. So as a result there isn’t this great content reuse model. So that the typical thing you would do in Microsoft Word, maybe you need a derivative of that training manual, is to do a “Save As” and make a copy because maybe you have an audience that needs that training manual but some of that content needs to be removed because they don’t need it. But again 80% of the content is identical between these two training manuals. So if there’s any future edits, now you have to remember to make edits in both of these documents and so that may be a little inconvenient but maybe you can deal with, you know, one version of this training manual to maintain but the big problem happens if you have to do this exercise of “Saving As” more than once because you know again, your audiences may change slightly and there may be a lot of things form that initial document that these different audiences can reuse. So, in Word you have to constantly do a “Save As” and either add or remove things that you need. So, the more of these things start to multiply, the bigger the problem and the headache becomes and if any common content needs to be updated and changed, well now you’re having to make edits across multiple Word documents or Google Docs or whatever you’re using. So you get to a point where you practically have to keep a separate spreadsheet of where and what you edited and really map where a change may affect other derivates that you now need to maintain, which can be a huge giant mess. So, with conventional tools like Word, you’re always editing and hand touching those end deliverables, which keeps an author stuck in that inefficient work flow.
[Weber] So then the advantages of topic-based authoring are that it makes revisions easier, that content can be repurposed? Can you talk a little more about-
[Morse] Yeah.
[Weber] -these advantages?
[Morse] You’re on the right track. So really, the big advantage is that it really helps make content reuse possible. So, topics can, when their constructed properly, again without reliance on some other content for its meaning, they can be used in any context, anywhere that’s-that they’re need and be maintained as a single source. So, the whole idea is to only edit and update our source materials. So, when we-we want to get to a place where you know a particular topic describing “Procedure X” only lives in one place. Even though it may end up living in 20 different pdf files and it may be slightly different in each of those pdf files, but when it comes time to make an update or an edit to “Procedure X”, I’m not going to do a “Save As,” which is that initial instinct and make edits, I’m only going to update it in one place.
[Weber] Great, great. So, talking about the advantages thinking of it now about-what doyou need to do to make this work? Because it sounds as you’ve identified if there are folks that aren’t doing this already that it’s a big shift in thinking in the way that you approach a document, or I guess publication in general. What are some strategies that are necessary for making this work?
[Morse] One approach is to-is toreally look holistically at all of your content. Perhaps take an inventory of what you have and maybe your overall content goals. Then kind of see how can you repurpose anything that you’ve already got. If you’ve-if you’re currently in a place where you’re in this non-topic-based world, how can we take it and make it into topics? And so, using a topic-based tool is a great place to start to make that process easier and so being that you know we-we make great tools, I would be remised not to mention using MadCap Flare as your topic-based content management system. So that’s a really good thing to do. Is how can we get to a place where we’re not copying and pasting stuff? What can we do to break things up? So, Flare can actually extract all of your Microsoft Word content or content from other linear-based tools like FrameMaker. So, lists, stay lists, your tables, stay tables, and we have the opportunity to break that linear-based content into individual topics automatically using the styles that you have in place in your document already. And so, once we have topics, now we’ve got some chunks of information that we can work with. Now we can think about how to-how we can manage that content so that if you’re a single author or a team of authors, topics can be organized and found quickly and again Flare makes it easy to manage this modularized content. Okay, so we repurpose what we’ve got, we have the opportunity to create new topics and new content, then we can start thinking about content duplication because maybe we’re in a place where you were maintaining a lot of different Word docs and maybe there was a lot of stuff that was common across all of them. Once you’re in a topic-based world, now we can look and see, “Well where can we minimize this stuff,” and if you’re using the tool like Flare, you could even go a step further and create subtopics called snippets, which are reusable chunks of information that you may have to use over and over again. Perhaps this may be a series of steps that are-that are the same across all of your content or maybe it’s even a sentence like you know if you’re documenting software sometimes you see, “From the file menu select,” you know it’s a-it’s a chunk or a sentence or even content in line in a sentence that is used over and over. And so these little chunks can be configured as subtopics, which we call snippets and it’s inserted into your topics by reference so that if there’s any change to one of those steps that you use over and over, even just a word change, yeah everywhere that snippet is used the content updates automatically, which can save authors a ton of time and reduce a lot of that duplicate stuff.
[Weber] I have another question. So, is part of the strategy for topic-based authoring that there’s kind of a standard structure for topics featuring the same kind of content? Is that correct? So, in other words procedure topics would all be structured in a similar way and is that-is that something people usually do?
[Morse] I think so. I think that the nice thing about something like Flare for example is that it-it gives authors the flexibility to design and organize their topics anyway they want. So, I-it’s, it’s common to incorporate some kind of structure like that. So, you’ve got reference topics, you’ve got procedural type topics, kind of following an element of structure without the rigidity maybe of something like DITA.
[Weber] Great, great. Well thank you so much. This is very helpful and I think it’s a good introduction to people who are maybe thinking about making the switch or just want to know what topic-based authoring is, so thanks so much for joining us today.
[Morse] Oh thank you so much for having me, it was a pleasure.
[Weber] I appreciate it.