Podcast: Play in new window | Download
Subscribe: Apple Podcasts | Google Podcasts | Stitcher | TuneIn | RSS
Sarah O’KeefeTechnical content strategy has evolved dramatically over the past 25 years, and Sarah O’Keefe has had a bird’s-eye view of the whole process.
As the CEO of Scriptorium, a leading content-operations consultancy, Sarah has both witnessed and participated in the massive changes that have unfolded in the world of technical documentation.
We talked about:
- the technical- and product-content work that she and her team do at Scriptorium
- the job of technical content: “to enable people to do things”
- the challenges of building complex content that draws on information from multiple sources
- how content ops helps govern and guide the process of retrieving content from multiple sources and integrating it on a page
- the paradox of how technical documentation can sometimes be more accurate than original designs because tech writers have documented the features that engineers actually built
- how revealing the cost in both time and money can help disconnection problems like these
- the differences in tech writer staffing between countries like the US and Germany
- the importance of helping non-content professionals understand their role in documenting products
- the difference between internal documentation like code comments and user-facing tech docs
- the new “Content as a Service” model, which inverts old publishing models
- the rise of the need for structured content, as content is increasingly being assembled instead of created
- her plea to creators to quit hoarding their content
Sarah’s bio
CEO Sarah O’Keefe founded Scriptorium Publishing to work at the intersection of content, technology, and publishing.
Today, she leads an organization known for expertise in solving business-critical content problems with a special focus on product and technical content.
Sarah identifies and assesses new trends and their effects on the industry. Her analysis is widely followed on Scriptorium’s blog and in other publications. As an experienced public speaker, she is in demand at conferences worldwide.
In 2016, MindTouch named her as an “unparalleled” content strategy influencer.
Sarah holds a BA from Duke University and is bilingual in English and German.
Connect with Sarah online
Video
Here’s the video version of our conversation:
Podcast intro transcript
This is the Content Strategy Insights podcast, episode number 138. Years ago, people learned how to use complex equipment and software by reading physical documentation, actual books that made a resounding thud when your boss dropped them on your desk. Nowadays technical documentation is delivered almost exclusively in digital form, often inside the same interface that operates the product. Sarah O’Keefe has had a front-row seat as technical content strategy has evolved from old publishing paradigms to these new user-focused methods.
Interview transcript
Larry:
Hey everyone. Welcome to episode number 138 of the Content Strategy Insights Podcast. I am super delighted today to welcome to the show, Sarah O’Keefe. I’ve been listening to Sarah’s podcast, The Content Strategy Experts Podcast from her company Scriptorium for a long time. I just love it and I’m so delighted to finally have her here to talk about her work. Sarah’s the founder and the CEO at Scriptorium. Well, tell the folks a little bit more about Scriptorium and what you do there, Sarah.
Sarah:
Well, we’re consultants and we work in content ops. We do work at the intersection of serve content, especially technical and product content, publishing and technology. As to what I do, I’m afraid the sad reality is that I do keynote and Excel. So, I used to get to do cool things, but these days I run around and I talk about big picture things and I tell you all about my wonderful people who do really great work.
Larry:
Well, that’s great. And that’s one of the many reasons I wanted to have you on is that you’re in that, you’ve ascended to that position. You’ve earned that position as the boss and the lofty person in the business. But also from that lofty perch, you’ve had a chance to watch this whole field. We were talking just before we went on the air, I said, “You have the shortest LinkedIn profile of anybody I’ve ever seen.” You’ve been the CEO of that company for 26 years or something like that.
Sarah:
Yeah, something like that. I started when I was two.
Larry:
And you’ve seen a tiny bit of change over that period. Can you talk a little bit about how technical content, the practice of technical content strategy has changed?
Sarah:
Well, I guess for starters, technical content strategy didn’t exist as a phrase or as a concept when we got started. I would also argue that this is less a lofty perch, eagle soaring over things, and more like a slog to Mordor. But it’s been fun. It’s been really, really interesting and I’ve learned a lot of stuff.
Sarah:
And I think that in terms of evolution, the tools have changed, the software landscape has changed, and the demands being placed on content producers have changed. What hasn’t changed is the need to do what we need to do. So, we sort of have to keep in mind at the end of the day, and I’m going to set aside the Tolkien reference because this is going to go very badly when we start talking about the one ring and how we really need it. But, Tim O’Reilly back in the day said that the purpose of technical content is to enable people to do things, enable them to use your product, enable them to use your service, enable them to get their job done.
Sarah:
So, our job as sitting on the technical and product content side of things is to make sure that people get the information that they need so that they can get their job done. Now, there’s some subtleties in how that works and where you go with this and what the tools and the technologies look like. And in 1996, ’97 and in the early 2000s, we were still producing books, actual books with pages and covers and things that you could drop on a desk and it would make the satisfying thunk sound.
Sarah:
These days it’s all web. There’s some print still, but clearly the web and HTML are the priority. And because we’re digital, we can do some really interesting things around, again, providing people with the right information. Not here’s 800 pages, but rather, “Oh, here’s the exact piece of information that you are currently looking for.” So that’s our job is to enable that.
Larry:
Nice. And the way you just said that there’s that classic definition of content strategy that many people have modified the, I forget, I think maybe Kristina Halvorson or Scott Abel, or somebody originally said this, getting the right content to the right person at the right time. And then Val Swisher has added on the device of their choice and then the right context and all that. But all that points back to this being, even though it wasn’t called that, you were doing content strategy. Is that safe to say?
Sarah:
I think that, yes, in the sense that we were saying what are these tools that are out there and how can we best apply them to get the job done? Now, the supreme irony is that we’re all content people and we can’t get any sort of agreement on the actual definition of content strategy. And people will say things like, “Well, what you do is actually content engineering or content operations” or whatever.
Sarah:
I like to step back and instead of going with those particular labels – although if pressed, I think I’d say content operations these days, because we’re so technology focused – but broadly, our job is to figure out how to take content, publishing requirements and technology and intersect those three and get the job done well.
Larry:
Yeah, and still in service to that original idea of enabling somebody to do something. What’s striking to me about that is how much that’s like, like I’ve kind of evolved into a UX practitioner. And in that world, it’s all about helping people accomplish tasks. And when we talked about this a little bit when we talked a few weeks ago about the connection between UX content and going back to technical content, that it seems like, I don’t know, it seems like it doesn’t always seem like there’s a clear connection between them, but they sure feel connected. Do you have any thoughts about that or any impressions?
Sarah:
So, it’s interesting because when you and I talked and there’s a really great podcast with a bunch of interesting content that Larry has that we should probably cross-link. When you look at UX content, the purpose of content on a screen or the purpose of a web app is that somebody is trying to do something, whether it’s play a video game or pay their bills or whatever, book travel, whatever it may be. And the better the interface is, and the better the content is that you provide in that interface, the more likely it is that they can get their job done without ancillary supporting content that sits outside of that app.
Sarah:
The lack of integration though is really quite problematic because if you… Take the travel example. If I go in and I go to book a flight from point A to point B, okay, fine, I probably know how to do that, unless I’ve never traveled before, in which case I don’t know how to do it. But what does it mean to book a low-cost carrier? What does it mean to travel to another country and there are visa requirements? So, you’re going to sell me a ticket to get from point A to point B, but if you don’t tell me, “Oh, by the way, there are visa requirements,” which are not going to fit on screen, they’re just not.
Sarah:
And not only that, you don’t want to embed them in your app because they change. So, you have to say, “Oh, for your visit to India, you need to go talk to the government of India and make sure that you get the right kind of visa so that you can… And this is how you do it.” Now, you may pull that content directly from some sort of a government website or you might link it in, but what you don’t want to do is put a copy in your app because now, when they update the rules or they change their rules, you’re in big trouble.
Sarah:
Also, did you just assume that I’m a US citizen and do you already know that? Or am I a citizen of another country? But the travel app made the assumption because I’m booking out of the US, I must be a US citizen. Here are the rules for US citizens. Well, maybe I’m Canadian. Maybe I’m something entirely different. So you have to be really careful. And I think it’s fair to say that UX will get you, we’ll call it Level One of using the app, but when you get into these weird twisty use cases, you’re going to have to provide additional information and you’re going to have to find a way to provide that in the right context so that I can get my job done or my task done, which is, it’s actually not to book a ticket. My task is to get to India. That’s what I want.
Larry:
Yeah. And the real test-
Sarah:
I actually don’t care how.
Larry:
And the real test is to just-
Sarah:
And I really don’t want to be turned away.
Larry:
Yeah.
Sarah:
Right.
Larry:
Exactly. Hey, a couple things you just said there. You both talked about, I think you were talking about the substantive content that’s in there that the UX content is kind of around and that’s got to do its job. Then you also mentioned that sourcing of the visa information, you better get that right. You can’t just copy it because then you’re going to be cutting and pasting the rest of your life and you might be giving out the wrong information.
Larry:
That kind of speaks, both of those instances, I think speak to the increasing decoupling of content from its presentation. We’ve been doing that for a long time, but that’s, tell me, I know there’s a lot to that, but just in those two examples, the example of the substantive content that goes in, that the UX content is guiding you through and the need to source the right content, that you want to source it from the definitive source rather than just copying in some visa thing you read six months ago. Can you talk a little bit about how you manage that assembly process?
Sarah:
So, at a high level, we’re going to be looking at the question of, well, where’s content originate and who is the authority? Who is the owner of this content? And picking a government source is actually not really the best example because what’s more likely is that you have sort of what fits on the UI, and then if you want to drill down and get some more information, you can, but that’s still content that we produced internally. And then at some point we’re going to send you over to visa land in country, A, B, C, D, E, F, G.
Sarah:
So, what we have to do though is we can say, well, we own the UX content on our app or on our website or whatever we’re doing here. But then we want to make a very clear distinction between the content that we own versus the content that we don’t own. We don’t own flight rules. We’re just going to slurp those in from the various airlines. We don’t own visa rules. We’re going to have to bring those in.
Sarah:
And so, at a high level, what’s going to happen is that you want to really think about, Where does this information originate and who owns it, and how do I reach over and get that information from the owner if I want to present my environment and wrap it in my UX or UI or formatting, then I can or should be able to do that. Of course, if they’ve pushed it as PDF, then I have to just sort of accept the PDF and move on with my life.
Sarah:
But if they’re pushing it in some way or making it available and we can pull it in some way that is format-free, then we can potentially use that content and reformat it and make it look as though it’s part of our content. Although probably we want to be pretty clear that this is externally sourced. We didn’t write it. We want to say, here is the latest and greatest information from the US government or from the government of whoever, which we pulled this morning, or which is up-to-date as of thus and such date, or which we don’t have to say anything because we’re pulling it live. So it’s always up-to-date and that’s not a question.
Sarah:
But the trick is that if you think of your content as a collection of boxes, not visually necessarily, but there’s the box of content that I authored and there’s the box of content that someone else authored, and there’s the box down here that some third party authored. And what I want to do is in each of those buckets, I want to make sure that I’m pulling in the content from the source, the authoritative source, whoever that is, and that I have either a live or close to live connection or something that reaches out and pings and says, has this changed? Oh, it has. Let me go fetch the update so that what I have is always up-to-date and when I’m presenting it inside this environment.
Sarah:
You can make a decent argument for, we’ll just give them a link and click them over to the source instead of embedding it in my environment. But from a customer experience point of view, probably it’s easier to, for me, again, as the ticket booker person to sit in a single environment instead of being sent all over the place to get the right information.
Larry:
Right. And that’s sort of a lot of it, there’s a couple things that just come out of what you were just saying is one, sourcing that stuff, there are still places that’ll just hand you a PDF, like every restaurant in the world. I don’t know what’s going on with that. But increasingly the hope and the expectation even is that you’ll get an API that you can access that will have pretty accurate stuff. But also when you were talking about your own versus other’s content, there’s also seems like there’s some governance and legal compliance stuff going on in there. Can you tell me about how content ops helps with those kinds of issues?
Sarah:
Well, let’s talk about the tax code. Because that’s a fun topic.
Larry:
Okay. Everybody’s favorite.
Sarah:
Everybody’s favorite. All right. So, let’s say that you’re doing your taxes and probably you have some sort of an app to do your taxes. And in order to do your taxes correctly and successfully, you have to probably look at information that in the United States is coming from the Internal Revenue Service – in other countries from the local equivalent – in order to understand what do I have to put in this particular field on my tax forms?
Sarah:
Actually, I heard this rumor that other people, it just magically happens and they don’t have to file taxes in other countries. So, maybe this is a US specific example. So you’re going along filling out your form and you’re really angry, but you need to source the actual rules because the rules are complicated. So I need them from the IRS. I’m not going to rely on what you wrote as a tech writer telling me, “Well, my interpretation is this,” unless maybe you’re a CPA, and then I’ll think about it.
Sarah:
So I need that sourced, and my hope would be that the IRS is going to make available what amounts to a data stream of their content, of their regulations where I can reach in and say, give me everything that’s relating to line 57, or give me everything related to this particular tax form. Give me all the instructions, give me all the details, give me all the background so that I can read that, possibly understand it, but probably not. My CPA can read it and understand it and tell me what to put in there or put it in for me.
And so it becomes very important to provide that information and be very clear about is this interpretation or is this the actual guidance? Is this the actual IRS rule? Or is this some very aggressive accountant saying, “Oh, you don’t have to do that. You can get around this and you can totally fill in a zero and everything will be great.” And I personally have this thing about not going to tax prison. That doesn’t fill me with joy. So I want to get it right or at least right enough to be defensible.
Sarah:
So, in terms of content ops though, stepping away from this, it’s very, very common to have multiple content sources that you need to integrate on the page. And what you need to do is really understand where they come from, who’s authoring them, how authoritative are they, how reliable are they, and how do I work through that?
Sarah:
So, what if you don’t have a reliable source? So, for example, we had a case in a project years ago where there were 3D drawings, CAD, so design drawings of a machine of some sort. And so if I’m writing technical documentation, I probably want some of these design drawings integrated in what I’m doing on the doc side. You talk to people and you say, “When you’re doing maintenance on this, you need to remove this wire and put this other wire on” and blah, blah, and you get wiring diagram. Great.
Sarah:
Well, it turned out that the as designed wiring diagram and the as shift wiring diagram were not exactly the same. So the product would be designed, and they made a wiring diagram, and then the product got improved as it was being actually built out. “Oh, we didn’t need to do that. We can simplify this, we can remove some pieces and parts and kind of make it better.” But those decisions did not necessarily make it back into the design drawings.
Sarah:
So the tech writers were getting design drawings that were actively wrong compared to the actual shipping product, and there was a months long knock-down, drag-out over who was responsible for making sure that the design drawings were actually up-to-date.
Larry:
Well, that sounds like one of those issues that is, not unique to, but a real ongoing concern in technical content, that integrity from, you want those, like you said, it’s all about enabling people to do things, and those instructions better match the actual gadget or interface in front of them. Is that an operational thing? Are there content ops practices that can prevent that kind of thing? Or tell me how you resolved that and keep it to a minimum, I guess.
Sarah:
It is 100% a political problem. The engineers didn’t want to do it because it was additional effort and they were doing enough documentation to get this thing down the line and get it assembled and built successfully. And so, as far as they were concerned, they did their job because they defined their job as get the product off the assembly line and out the door. But because they weren’t updating the drawings, what actually happened was that the out of date drawings went to the tech writers who then spent umpteen hours fixing them, cleaning them up, correcting the divergence between the actual drawing, like the original drawing in the engineering system.
Sarah:
And so what happened was that the technical documentation ended up being more accurate and more up to date than the engineering source files because they made the changes downstream, not back in CAD. So we gave them a couple of different options, like A, update CAD and keep it up to date. And then there were subparts like give the technical writers access to the CAD stuff so that they can update there instead of updating on these downstream versions of it.
Sarah:
Anyway, it was a whole big mess. But the gist of it was when you, the engineering team, choose not to keep this content up to date because you don’t see it as part of your job, because they defined their job narrowly as “get the product off the line,” and they were busy. They were busy and overwhelmed and all the rest of it. I’m not unsympathetic to what was going on there, but I’m looking at the content, and what they did was they put a roadblock in front of getting the content right.
Sarah:
So we had to remove that roadblock and find a way to get it right. And ultimately, it was far, far cheaper to clean up the CAD files than it was to rework them and have to do all this research to figure out what was going on and rework the downstream. It was like illustrator files or something, and they were no longer CAD because it was “Oh, it’s too expensive to put you people in CAD.” Well, okay, but it’s really expensive to redraw these things and clean them up and do all of that by hand.
Sarah:
So, ultimately we uncovered the cost issue. So there was a cost issue, but there was also a time to market issue because it takes a stupid amount of time to redraw things as opposed to rework it in the CAD system. They needed to get closer to the source, clean it up there and make it go. I’ll say also, separately from this particular incident, another very, very common problem, similar but adjacent is, “Oh, well, we can’t get that information extracted out of the system.”
Sarah:
The source information lives over here in System A and System A doesn’t have an API and doesn’t talk to other systems. And when you export from it, you get something dumb and annoying that is hard to rework. So, again, roadblock between what we need, which is just reach in and grab the stuff and have it be accurate and have it be rendered – accurate, up-to-date, rendered – and “Oh, that system doesn’t do export, not in a meaningful useful way.” That’s a technology problem.
Larry:
Yeah, and I want to go back just a little bit to the story you’re telling about the engineers, the discrepancy between the CAD files and the Illustrator files down the road and what the end user actually saw. There’s two things in there. One, that sort of provenance along the ways, like who owns what, who’s responsible for what. But also I think it goes all the way back to who actually writes the docs.
Larry:
I think a lot of people, I had this idea for a while that, oh, technical docs, technical writers write that. It’s like, no, half the time, two thirds of the time, I don’t know what percentage of the time it is, it’s engineers or other people documenting stuff. I guess maybe, so that’s my first question would be in terms of all the technical content that exists in the world, what percentage of it is done by engineers and the builders? I know that’s a stupid question, but I think you get the intent is to what percentage of it is written by the designers, the builders, the documentors, if that makes sense.
Sarah:
I don’t know. What I do know is that if in the US, if you look at Bureau of Labor Statistics, there’s about 50,000 people that are labeled as tech writers or some category like that. It is quite clearly not 50,000 people in the US that are writing content. So, my best guess would be that it’s probably in the vicinity of about 10%, but I don’t know that. And then that’s a US-centric view.
Sarah:
If you look at Europe, if you look at Germany in particular, they have nearly as many people with the job title of tech writer or their equivalent. They have nearly as many as the US does, and they have a much smaller population.
Larry:
Interesting.
Sarah:
So, we’re 330 million, and I think they’re about 80 million. So they’re about a quarter of the population, but the ratio of the number of people employed as tech writers is actually very close. So that implies that either, well, I don’t know what it implies exactly, but I think what it implies is the higher percentage of people are actually labeled as tech writers relative to the number of people that are doing the work then in the US. But I don’t know what that looks like.
Sarah:
It turns into this question of how many people are tech content adjacent and when is that part of their responsibility, and do you count them if it’s only 5% of the time, and do you count your reviewers and all the rest of it? But, I will say this, the root cause ultimately of this, what we had is an engineering and political problem, there was a resourcing issue there. Everybody was under-resourced and overworked.
Sarah:
But the clearest way of looking at this is to say the documentation, when we’re talking about operating instructions, service manuals, those kinds of things for hardware, and of course we have similar things for software, and I would include UX writing in this bucket, the content that actually appears on a software app, because we have this whole continuum, and of course we have tons of hardware that actually also has a software component. You have a machine with an interface on the front of it.
Sarah:
So now what? Now you have UX writing and… Anyway. The operating instructions, the enabling content is part of the product. It is not a nice to have. It is not this cute thing that you do later. It is not this thing that you get to blow off because you’re the cool engineer who’s doing industrial design. It is part of the product and is part of the design. And your user experience, quite clearly, when you’re operating a machine, your user experience is affected by product doc. If you can’t figure out how to use a machine, either you’re going to be unproductive or worse, you’re going to get hurt or worse.
So, we need to be very clear about saying you don’t get to just slough off your product responsibility because, “Oh, I’m not a writer.”
Larry:
Right. And I wondered, the way you just said that also reminds me back to the very start of the conversation when you talked about content strategy. What does that even mean? We can’t even get our act together enough to describe accurately what we all do. So maybe that’s part of the issue too, when the Bureau of Labor Statistic comes around asking who’s doing what? We’re like, “I don’t know. He does some writing, I guess.” Yeah.
Sarah:
Yeah. And software developers, you’ll see tons and tons of people that are documenting their code. Well, does that count? It’s writing, if you’re writing code comments. And the better your code comments are, the more maintainable your software is. That’s not user experience. It’s not end user. It’s like internal users. Because the next person that comes along and touches that code needs to understand what did you do so that they can make the updates. So there’s that. That’s more like I’m writing content so that the next person that updates my product, my software product can also do their job.
Larry:
Exactly. That’s funny, in the UX world-
Sarah:
There’s a world of this stuff.
Larry:
And in the UX world, in particular lately, it’s like I’ve just had a lot of conversations and seen a lot of social media talk about how an increasingly high percentage of UX work is enterprise UX work, the internal work, and similar.
Larry:
Hey, Sarah, I can’t believe we’re already coming up close to time and I could literally talk forever about this stuff, but we should probably wrap it up pretty quick. But I want to give you a chance, is there anything last, anything that’s come up in the conversation or anything that you just want to make sure we share before we wrap up?
Sarah:
Well, you and I had a really interesting talk about fragmentation. The things that I want to drop in here that we haven’t had a chance to touch on are, when we talk about being able to pull content, what we’re really talking about is content as a service, which is sort of this new idea that essentially inverts publishing. So that’s something to worry about.
Sarah:
We are trying to increase the maturity of content development, content operations, content everything. And that typically means that we’re looking at producing content in smaller and smaller bits so that we can mix and match and repurpose and reassemble them there. There, we’re looking at concepts like structured content, which is a whole conversation in and of itself.
Sarah:
But I think that the way I look at this is that we want to provide our content producers or our content end experience, we want to make sure that what we’re delivering is accurate and usable and up-to-date and relevant and all these other things. And in order to do that, we need to clear some of these roadblocks out of the way. You mentioned copying and pasting. Okay, number one market share content management system in the world is what? It’s Microsoft Excel.
Larry:
Word.
Sarah:
No, I think it’s Excel. It’s content sitting in spreadsheets.
Larry:
It’s Excel. No, you’re right. Well, especially in our world. Yeah, yeah.
Sarah:
Yeah. It’s content sitting in spreadsheets. Now, a spreadsheet is kind of like a baby database, so it’s perhaps not the worst thing in the universe, except that when your content management system is the Excel spreadsheet that is sitting on my local hard drive, that’s bad, like really bad. And so my plea is to say, we have got to break out of this idea of content hoarding. I’m going to write the content and stash it away on my system and you can’t have it. Well, maybe you can if you ask nicely.
Sarah:
No, it’s an asset that belongs to the organization, and we have to make sure that it is mobile, it can move around the organization in an effective way. And you’re my spreadsheet, not going to do it. It works fine as long as I’m the only writer.
Larry:
But as soon as you have to do anything else, and I can see how that ties in with the content as a service. If you have that as a company prerogative, you’re like, “We can’t really serve this up from your spreadsheet. Can we put this…” And then that gets into a whole other conversation about CMSs and-
Sarah:
Right. Nope, it’s my content. You can’t have it.
Larry:
Yep. Yeah.
Sarah:
I’ve had those conversations. It’s super fun.
Larry:
Well, that’s why, and that comes back, that’s the running gag I think in this podcast, is that it’s all about people, that it ultimately comes back to, you were mentioning the political issues with the engineers and the guy hoarding the content. It’s like, yeah, it’s all people stuff. So…
Sarah:
It’s all people stuff. The technology’s fun and interesting, and we can enable some really awesome stuff with it, but the people come first. Yep.
Larry:
Excellent. Hey, oh, one very last thing, Sarah. What’s the best way for folks to get in touch with you online if they want to connect?
Sarah:
So if you go to our website, which is scriptorium.com, and there’s all sorts of stuff there and including ways of contacting us and all the rest of it. But you can email me. You can use my last name and take out the apostrophe, which is a whole thing, or just email info@scriptorium.com, and I will get that.
Larry:
Great. Well, thanks so much, Sarah. I really enjoyed the conversation.
Sarah:
It was great to see you, and thank you again.
Leave a Reply