Topic Writing Without Borders

[00:00:00.120] - Liz Fraley

Welcome to the TC Dojo from Single-Sourcing Solutions, TC Dojo is a Tech-comm community that is driven by you. Tell us what you want to learn, you choose the topics and we find the experts. In the TC Dojo open session today, we have our very own Janice Summers from Single-Sourcing Solutions. Janice specializes in helping people who've only ever used unstructured, desktop publishing applications, learn structured authoring. She's been successfully transitioning word users to XML authoring for the last 15 years, and she hasn't lost anyone yet.

[00:00:34.200] - Liz Fraley

She's also the Chief Interviewer in Room 42. We're happy to share a taste of the training we provide to our customers on Minimalism Personas and Topic-Based Authoring with you today. Even though this is just a taste, Janice does have a lot to cover. So save your questions until the end, but be sure to type them in when you think of them so you don't forget what you wanted to ask. Janice, it's all yours.

[00:01:00.020] - Janice Summers 

Thanks for taking the time and spending some time here with me at the TC Dojo, it is a delight to be here with you, and today I'm going to talk about Topic Authoring and I'm talking about it without borders. Now, in case you associate topic authoring with DITA, you're right to do so, I'm not here to teach DITA. DITA is fantastic, there's a lot of depth to it and there's a hefty thing to learn. I'm just going to extract some really great, cool things that come from the discipline that often associates itself with DITA, and from one of the cool key things in DITA and that's the Concept of Topics. But this topic authoring can be applied to anything, any architecture it doesn't really matter. That's why it's topic authoring without borders, because it's light without all the overhead and it can be for everyone. It really truly can.

[00:01:56.570] - Janice Summers 

So first, I want to talk about the goal of every writer, and this is the same whether you're a professional or a technical writer, we all share the same goal, and that is to make the complex easy for people to understand right, we're transferring knowledge to them so that they can achieve something or complete a task or a goal. That's really what it's all about for all of us, and the more effective we can be, then the better satisfaction for the end users and that's what we're about -- as happy end users or happy customers and it makes us better. So that's the purpose of Topic Authoring. That's the goal behind all of this. So let's talk about what we're up against, and this is the same for all of us. And you as an individual are up against this for yourself.

[00:02:50.240] - Janice Summers 

So there's this interesting study that was done University of California San Diego, and they recently refreshed the study, so it was done like you know a decade ago and then they re-did it again just to check and see, are we in information overload? Like, how much information are we trying to digest? And they did a study, It was US-based, so it's only in America. So it's a little limited and it's pre-pandemic, but at the time that they did this, they discovered that the average person spent about 12 hours of their waking time, consuming content. Now when I talk about content consumption, it's televisions, radios, smart devices, computers, emails, all of those things, reading books, that type of thing. So that's consuming content. Now, on average the person is greeted with about a hundred thousand words per day, that's twenty-three words per second.

[00:03:54.920] - Janice Summers 

And I think the fastest reader and the smartest people can really only read about five words per second. So we're definitely served up a buffet of a lot of content and some we can't -- it just can't even hit us, we can't even digest it. The nice thing is though we do have as far as mental capacity who can store on average, about thirty-four gigabytes of data I think a day, now you're not going to run out of storage space that's nice, they never really have tapped into how much information we can store and how big our memory is. They've estimated I think at about five petabytes I think is the phrase, anyways what that means is you could turn on a television playing non-stop programs for twenty-four hours a day, 7 days a week for three hundred years, and you wouldn't even hit the top of our ability to store information.

[00:04:54.320] - Janice Summers 

But let's talk about the mental processing, which is really what we're focused on when we're talking about professional and technical writing. We want to capture their conscious mind that's what we're after. So let's talk about mental processing as far as conscious mind now when we're in conversations face to face, and this is separate by the way, from this other information we're consuming, those conversations we process about 100 megabytes of information per second. There's a lot of activity going on because when we're face to face, all of our other sensory's are acting as well. We're not just reading, we're actually listening to the tone of the voice, to the inflections, and we're trying to extrapolate meaning from these other things. So when we're face to face, we have small  and sight, when we're in Zoom, we at least have sight, we don't have smell, but we have other sensory things that are engaged. So it's a lot of processing that happens face to face. Now, at the same time the human body is sending information, the brain is processing, it's the central area to send the synapses to make everything work. And the human body is sending about 11 million bytes per second of information. And that's because it's interpreting external clues, it's also helping you digest your food, it's helping your heart to pump, it's regulating your body for you. It's telling your eyes to blink, a lot of things are happening that you're not necessarily conscious of.

[00:06:28.970] - Janice Summers 

What we're worried about is the conscious mind. Now, the conscious mind can only process on average about 50 bytes per second. So that's significantly smaller than all of the other information. But that's the conscious mind that's actively retaining and understanding and super -engaged, that's our task, is to tap into that in order to impart knowledge. That's where we're hitting, right we want to monopolize that cognitive process window. Now, on top of all of these other things that are going on for this person, they've got external forces and if ever you've worked at home and you've worked at home, like in the last year and there's been more than one person in your household working from home, you know how easy it is to get distracted and you know all these other stressors that are being pushed on you.

[00:07:20.450] - Janice Summers 

So imagine yourself in the situation where you have to suddenly learn a new technology or you have to troubleshoot a software that you're using, and you have to go look up help documents. This is the person that you're writing for right, hopefully you're not writing to them, hopefully you're writing for them, and that's going to be one of the big differences that hopefully I can impart you during this session and again, we don't have time to go in-depth too much. But I want to get you a brief understanding. So how successful do you think you're going to be if you're writing long-form and more traditional right, where they have to sift through information? Not very. You're going to end up with a frustrated customer. You might never hear from them, but you're definitely imparting a negative emotion, you could right. So now I'm going to go over and kind of give you some of the basic rules, and I want you to know I'm not saying these are the edicts and you must do this or that or the other.

[00:08:24.620] - Janice Summers 

I just want to give you some of the basic rules so you know how to break them for yourself and how to apply them, because if you're going to do Topic Authoring, you really need to own it. You need to own it for yourself and for your company. I know Liz gives a lot of really great presentations on guides, and I know we've done a lot of training with our customers on guide, style guides, authoring guides. These things are so important because they help you personalize the rules for your applications. And it is a critical, critical step for you to do right, don't rely on others you need to internalize this, digest it and create rules for your company. So the number one thing, and this is probably -- my favorite workshop is minimalism. I love talking about minimalism, and really when I do workshops, when we do workshops on this, it's a lot more in-depth and I don't have time to go into it but it would be terrible for me to mention Topic Authoring without giving you a glimpse of the idea that you need to say more with less.

[00:09:31.760] - Janice Summers 

I am pretty verbose, and I like to over-explain that's just my nature. I am one of those nurturing people that like to state the obvious and kind of, you know, explain to every little detail possible, and I do that but then I have to edit, edit, edit, edit. That's the name in the game. So if you're like me and you like to over-explain edit things, remove any distractions. So if you're doing infographics, this is especially important, if you're doing infographics, make sure they're clean and lean and easy to follow, that you're not putting too many words on there, and the words aren't complicated right, sometimes when I read some technical and professional writing, it's kind of like that sign at the amusement park where they say you must be this tall to ride this ride right, so it's like when you're reading this communication where they're trying to communicate to a broad audience and yet they make it so complicated that you must have this grasp of the language in order to understand what we're saying to you.

[00:10:38.030] - Janice Summers 

So you're trying to talk to lofty or high-hat when really what you need to do is find the common language, because you can't assume that everyone who reads your content has the same native language. That's the other thing, that's why you want to make things not so complicated and a little more simple when you're doing technical and professional writing. Because you may need to translate even if you're not translating now, it may need to be translated later. And perhaps someone is trying to translate it for themselves that the language that you're authoring in isn't their native language. So another thing you can do with minimalism is you're kind of liberated. And this kind of ties in also with the stating the obvious. In this day and age, depending on what you're writing and who you're writing to, you can make some assumptions, that they have knowledge, they have already gained some knowledge when they're coming to your content.

[00:11:40.520] - Janice Summers 

And that's why they're just looking to solve a problem, they're not looking for a backwards knowledge, they're looking for forward knowledge now granted, some people are in some professions where you do have to state the obvious. It's kind of a law. So things in the medical field or things in heavy equipment where you really have to make sure you spell a lot of things out, it's understandable, but you can still make things easy and you can still remove distractions. So there's still something for you in minimalism, no matter what discipline you're writing for.

[00:12:15.440] - Janice Summers 

So the next thing that we run into a lot is Everyone is My Customer. This is the first thing when I started these workshops on persona and I'm like everybody's my customer. Well, it's easy to think that everyone's your customer, especially if you're doing help topics for like web applications like social media, web applications, like everybody could be your customer. So it's a little challenging, but it can be done. I tell you, with every customer that we've worked with and we've helped them build personas, we have found their persona and we get a little creative and we go a lot deeper than what's here on the surface, but everyone's got personas. Every customer of ours has personas or the audience that they serve. And it's important for you to really know who they are and understand why they're reading your content. I think that's the first question I ask a lot of times when I'm teaching people DITA, when we're teaching people Topic Authoring without borders is why is the person reading this information? Who are they and why are they there? Very important to understand okay, because chances are they're there to accomplish something. They're there to do some task or they need to understand something deeply.

[00:13:38.820] - Janice Summers 

So you need to appreciate what they're trying to achieve right, you need to see things -- Liz recently did a presentation on what we call inside-out versus outside-in. So a lot of times traditionally we are asked to explain features and explain the product to customers. That's pushing information from the inside-out. But when we're understanding our audience and we're taking on their mantle and we're envisioning how things are from their perspective, we're looking from the outside and trying to pull the information that we need to do a task or to gain a knowledge right, to understand a concept or to reference some key information. That's what we're doing from the outside-in. So that's what it means when we talk about personas. And it's deeper than just the demographics, which is just age and education and you know the typical stuff. Personas go deeper because people are more than just that, all right.

[00:14:42.930] - Janice Summers 

So let's now talk about Topic Based Authoring. I always apply minimalist to it, because I think everybody should be minimalism right, I mean you know just get to your point quickly and succinctly, but what Topic Based authoring is, it's this independent chunks of information, so it answers one thing well. That's really the purpose, so when you think of a question, you think of somebody is coming to my document for a reason. What's that reason? And this is the answer. I'm just going to focus on answering that one thing.

[00:15:20.100] - Janice Summers 

Now I can give them see also right, so I can say hey, if you need more information, go over here right, or if you want something similar to this, go over here it's that whole see also, and that can help connect my documents, but I'm answering one topic right now right, if you've come here for the instructions on how to bake a cake, I'm going to give you the instructions, the tasks to do it. If you want to understand the principle of cake, or how cake was invented, I'm going to give you a link at the end or I'm going to give you a place to go to look for more information, right. So these topics can be connected yet independent. And they're really easy to organize and re-organize based on what your user needs and what you need to serve up to them so things can be reconfigured. That's what Topic Authoring is. And I can teach you this in two steps, it's a two-step topic. First, you have to streamline your content, so you need to look at your content and look at each part of your content and say, what are you trying to do?

[00:16:35.470] - Janice Summers 

And this takes work and planning and it takes looking at your content from a different perspective. But you want to divide things into three categories and you want to kind of force yourself to be really disciplined and pick these three standard categories, if you've got special things, set them aside as something that's too hard and readdress it later. It could be that you've got information that nobody cares about or you're trying to put something in that just doesn't fit and it's okay to edit that stuff out if it wasn't serving you, it doesn't serve your users, then get rid of it. So the 3 categories are people usually -- now they've done studies and this is usually where people are coming to when they're looking at professional and technical writing, they're trying to do something. So this would be a task right, each steps, very ordered, very organized, and very rigid. But it's important because that's what they're trying to do. If they need to use the heart monitor, then they need the clear, concise steps to do it. They don't need the invention of the heart monitor, all the purposes or any reference  information. They just need to know, how do I operate this defibrillation machine? Somebody's life's in danger and I need the steps. Clear, concise, minimal right?

[00:17:56.770] - Janice Summers 

Concept, so the concept -- you have less of these than the other two, that's just the nature of technical and professional writing, is we tend to have fewer conceptual ideas or theories and most of it is "meat" right, it's the substance and those are references when you're trying to give more explanatory information right, so settings and oh, my mind just went trigger. But explanations are what happen in references. Now, each company might adopt a little bit different slant on concept to reference and these things really do take practice to do, this is also the importance of an authoring guide so that you can clearly define for your company what each of these are with examples that are built for your company.

[00:18:57.250] - Janice Summers 

When we do work with our customers, these become very real for them because we use their content to help explain what we mean by a concept, what is agreed upon as a concept and what is agreed upon as a reference. They have running examples so they know when they're authoring, they can give their new authors guides and everyone can work from the same page. Tasks are really easy, tasks are so easy to find it's like you know, it's like candy falling from the tree. So that's our first step, easy yet difficult, but it's okay you can do it. The second step in topic authoring is to apply a repeatable structure. I like the Triangle as a good example of a DITA topic cause it's 3 sides, it's the most stable of all the geometric shapes. It's easy to configure and reconfigure a triangle into multiple shapes and distortions, but they all have the one thing, one side, one side of the triangle is the Title, very important.

[00:20:06.370] - Janice Summers 

The Title is that answer right, that someone is searching for. If you click on a Google search and you type in oh, I don't know, how do I install gutters on a house? Right, that's my question I'm looking for well, Google will turn up a bunch of search, results and those titles, those hyperlink titles, that's the title, think of that as your title for your topic, or if you do a table of content and you've got chapters and sections, have titles, think of it that way. It's that main point that's going to answer that question. So even if I'm in print document, you know that people aren't sitting down with your technical manual with a glass of wine and reading it cover to cover right, you do know that, so you know if they're trying to troubleshoot, they're going to go to the table of contents, look for troubleshooting guide, and then they're going to look for the subtopic and the troubleshooting guide you know how to replace my tire right, and that's where they're going to home-in, so that's the manual way of doing a search string in Google. So that's what the title is, it should answer that question. The short description is the next disciplinary thing and this is so important and oftentimes many people missed us. But it's really important to give a short description, that short description, it ties to the title, right which the title already answers, it doesn't repeat the title.

[00:21:41.500] - Janice Summers 

You don't need to say the same thing over remember mental real estate here. We don't have time to repeat what we just said, but we do have to add support to that title and give a little glimpse of what the body of the content is so that the person only has to invest the time to retain and understand a couple of sentences before they delve deeper right, it's kind of them saying okay, I've glimpsed this, yes, this is what I want, now I'm ready to settle in and really pay attention to the body of the information because you have the answers I'm looking for.

[00:22:21.250] - Janice Summers 

This short description also gives them the chance to say, close but not quite. Let me go see if there's another title that's similar that may be a better suit for me, a better fit for what I'm looking to do. That's why the short description is so important and even if you're not doing things for digital transmission today, chances are you will in the future or the content that you're authoring is going to get digitized. These short descriptions are great disciplines for you to have, and they can live actively in your document and they will serve a great purpose. It is a discipline to do them I get it, but it's an important one.

[00:23:07.030] - Janice Summers 

So those are the two steps to creating DITA topics. Now, the advantages -- sorry topics, we haven't gone to the depths of DITA, there's a lot more to DITA, but anyways Topic Authoring. So there's a lot of advantages in Topic Authoring, no matter what the architecture is that you're in. For a consumer, you can tell that it's easy for them to grasp, is this what I need for what I need to get done? And if it is, I'm going to be much more satisfied if you're making me wait through an in-depth paragraphs and paragraphs and paragraphs of information to find what I'm looking for, I'm going to get frustrated. You might not know it, but I'm not going to be happy and you may never know. So it's important for you -- this is another reason why it's really important for you to understand your users and if you do user testing, that's fantastic.

[00:24:05.180] - Janice Summers 

User testing is priceless. So for the writers, it's going to help you if you're collaborating, because you're all on the same page you've got your authoring guide and there's that -- so same style it's applied everywhere. And because we're streamlining and we're making things easier to understand. It really is easier to manage it. It also makes it easier for you to share content in multiple configurations, what if what you're writing -- say you're in an engineering department and your writing information was pieces of that information could be highly applicable to the marketing department, who has technical writing needs as well. So you can share that over with different departments in an organization, it can be reconfigured into multiple types of documents. There's really no limit.

[00:24:57.740] - Janice Summers 

This is also a key factor for re-use right, when you can re-use something over and over again in multiple configurations and it doesn't have to be uniquely authored all over again. So some really key time-saving factors as a writer. So things I want you to keep in mind, if you're tackling topic writing, know who you're writing for is really, really important and why they're reading it, this is going to help you really streamline and get to the point. You're going to answer one thing and one thing well. Don't compound your topics with oh, I'm covering a task and I'm going to throw in some reference. No, keep your task focused on the task. Remember, you can link over to other things if you're a digital, you can cross-reference over into other topics that they may find interesting. If they want to go deeper, if they need additional information, you can send them where they need to go, if they need it.

[00:25:58.700] - Janice Summers 

Chances are if you've answered one thing and you've answered it well, they don't need to go look at a FAQ because their answer is there. They don't need to go look any place else because you've solved their problem and they can move on. So again, relationships right, that ability to reconfigure things and the ability to say see also, really does help strengthen the big picture. So if you need to produce a large document end to end, you know that's those relationships of those topics coming together in one large publication and they can be stronger together.

[00:26:37.770] - Janice Summers 

All right, so that's I think about -- about time now, if you have any questions, I'm happy to take them. If you want to go deeper, a little bit deeper, I am doing a topic writing for everyone at the STC Pre-conference Workshop in June. So you want to join me for a live and highly interactive, this is where you're going to get work to do and we're all going to review it. So it's you know roll up your sleeves topic writing for everyone, it's not a DITA training class. It is topic writing for everyone. So that's on Saturday June, 5th so that's it.

[00:27:17.310] - Liz Fraley

Now it's time to type in those questions if you haven't already, and while you do, here's a look at what's coming up. The TPC Affinity Groups are monthly driven member discussion groups where attendees present their specific challenges to a group of their peers in a confidential, supportive environment. You can sign up at the TC Dojo website at tcdojo dot org. We know sometimes magic is just having the time to collaborate with someone who's been where you are.

[00:27:45.660] - Liz Fraley

Next time in the TC Dojo, next month, we have Bob Johnson, he's going to talk about Accessibility Basics, then review the categories of disability and why they're an important concern for writing professionals. It's going to be a really great session, so be sure to sign up. And Wednesday, two days from now, we have a candid conversation about future employability for writing professionals. We have Saul Carliner from Concordia University in the room. We know that employment environments continue to change, so be sure to join us as we talk about techniques and strategies that will help relieve that career anxiety. Sign up for these events and others. You can find sign up links in the calendar at the bottom of the page at tcdojo dot org.

[00:28:33.580] - Liz Fraley

I am not saying anything either you did a spectacular job, which --

[00:28:37.240] - Janice Summers 

oh their heads are spinning.

[00:28:39.160] - Liz Fraley

Heads are spinning, all of which are good, sometimes these are ideas that you need to think about. I know that I'll start off, I guess I know that -- well for me personas was very difficult, you remember that, personas are hard for me putting myself in someone else's shoes I never feel like I am qualified or capable of doing so.

[00:29:05.410] - Janice Summers 

It's a little different thought and I know there's people who think I'm persona, but they really are legitimate because we're not writing to Artificial Intelligence you know I think almost all of us they're writing to people and there are people and I cannot tell you how many times I've run into this situation where people are like everybody is my customer, right, but through working on it and working through it and getting outside of the typical demographic and really, really taking that aerial view and looking from the outside and we start to really discover who they are and who the personas are, who the people are. And it really does make a difference for the authors. I have never seen it not make a difference for the authors ever.

[00:29:54.350] - Liz Fraley

Yeah, so what we did last summer, that was just, it was kind of amazing how much improved their documentation -- and this is documentation all of you would know, you've all seen it actually, we're not allowed to talk about who it is.

[00:30:08.330] - Janice Summers 

Right.

[00:30:08.680] - Liz Fraley

But you have all seen it and it's getting better by the minute.

[00:30:13.580] - Janice Summers 

Right, this is another example of a customer, one of our customers, because we have more than one that can actually say everyone is my customer. If they had legitimate ground to stand on to say that and to think that right, but even they have personas that apply and so yeah that was fascinating because I've had you know people say oh well, no. Yeah.

[00:30:45.320] - Liz Fraley

But it's not always and that's always an awakening moment also -- oh yeah, I guess it isn't everyone. These kinds of people come to me and these kinds of people don't.

[00:30:57.230] - Janice Summers 

Right, the funny thing is you really honestly Topic Base Authoring is easy.

[00:31:11.090] - Liz Fraley

Yeah.

[00:31:11.090] - Janice Summers 

I think the challenge is in the practice of.

[00:31:15.980] - Liz Fraley

Yes

[00:31:16.490] - Janice Summers 

That's the discipline really is, the challenge, but if you're going to do things like  accessibility, and you're looking for diversity and all of the things that are really important that we're starting to pay more focus on, then you want to have this stuff down cold because in order to liberate yourself to really answer those other questions, this will help you get out of your own way in order to do it, to make things better and make improvements to address the needs of a more diverse audience.

[00:31:55.860] - Liz Fraley

Well said. All right folks, if I don't see any more questions we're going to let you -- we have one comment it says "thanks Janice you reinforce my last two techcomm courses very well. Indeed, that's right we're all good at it.

[00:32:12.780] - Janice Summers 

Well thanks everybody.

[00:32:13.920] - Liz Fraley

Thank you all for your time, and be sure to -- just a little closing out make sure you set up on the mailing list you guys all -- we'll add you to the mailing list anyway because you subscribe to the episode and be sure to take the survey if you haven't already. We look for topics that the community wants to learn, all right, so really we do look at this survey, and if you vote it in and you're allowed to vote over time, rechange your vote and it does change as we're interested in different things as time passes. So be sure to vote in the survey and as always, we'll see you next time.

[00:32:52.990] - Liz Fraley

Thanks, everybody.

[00:33:02.600] - Liz Fraley

Thanks for coming to the TC Dojo by Single-Sourcing Solutions where it's all about you. Subscribe to our mailing list at join dot tcdojo dot org. You'll get a link to this session, as well as announcements for future sessions and a convenient link to the survey. Every month we look at the survey results so we can go out and find experts willing to share their expertise. Why should we tell you what to learn? You should tell us.

[00:33:28.100] - Liz Fraley

Vote now at survey dot tcdojo dot org. As always, the TC Dojo is our pleasure to host. If you need more personal help and want to speak to one of our TC Dojo experts in residence, just go to ask dot tcdojo dot org, where you can get your question answered and be on your way. Thanks again and see you next time.