Ledge: Christopher, it’s great to have you on. Thanks for joining.
Christopher: Well, it’s great to be here with you, Ledge.
Ledge: Would you give us a background story of yourself and your work? You have a long, storied career and I would love to share this with the audience.
Christopher: Sure. A long, long, long time ago – not in a galaxy far away – I was a stock broker who was pretty unhappy with his career choice. After living in the over-the-counter world of selling penny stocks and all of that awful stuff, I decided to make a career change.
When I left, I was talking to a friend of mine who said, “You know, you do a little bit of writing here and there. Have you ever thought about being a technical writer?” My friend also knew that I loved tinkering around with technology as well. Apple II at the time, but I loved playing around with technology.
I started looking at it and I found out a little bit more about it. One thing led to another and I just started doing some contract work and some freelance work, and pretty soon worked into a job here and a job there. I wound up working for a lot of different companies over the years – Microsoft being one of them, EMC, Amazon, and then currently here at Tempered Networks.
Ledge: You’ve seen big names. Big names everywhere.
Christopher: Apple, IBM in there as well. It’s a nice little pedigree to have. It’s definitely nice.
Ledge: I’m a knowledge management, documentation aficionado myself. You have this sort of unheralded role where you touch everything. You know products better than anybody, and yet you’re in this… I don’t know. It’s like this middle seat where you get to view all the rest of the organization and how it all works together. You have an unlimited number of customers, internal and external. It’s just a lot to balance.
Conceptualize that role. You’re talking to a lot of engineers, you’re talking to a lot of product people, a lot of executives. That’s what we do here. I think the perspectives are so important from your seat.
Christopher: They are, if you can keep them all straight. I think that’s part of the problem, is you’ve got so many different perspectives, and sometimes even within the same group. You wind up talking to developers who have one focus that they’re looking at, and they want you to approach it from that way, and marketing wants you to approach it from a different way.
Sometimes they all mesh together, and that’s great, but most of the time they don’t. So you wind up kind of being a mediator in the middle, trying to make everyone happy as much as you can but also making sure that you’re the customer advocate here. That really, at the end of the day your job is to make the customer is successful.
Ledge: An analogy might be, I’m picturing the carousel at the mall. You’re in the middle of that cylinder going around. All the horses are there and kids are choosing their horse, but ultimately you’re the guy in the middle going, “But y’all, it’s all the same thing. We’re talking about the same stuff.” “But this is really important.” From every perspective, you have to be a master priority setter in that seat.
Christopher: That’s very true. I think part of it is people, they all have good ideas and good hearts about what they want and they all really want the customer to be successful in the end. They’re just approach it from their own – I don’t want to use the word bubble – I guess from silo. From their own silo. Their own perspective there.
I can talk to a developer who says, “Well, you’ve got to tell them how this works.” Sometimes my response is, “Do you need to know how the engine works to start a car? No.” You might need to know how that engine works if you need to repair it, but you don’t need to know how it works to use it.
Getting people to understand how much information to give to someone at a particular point in time. Too much information, they don’t want to read it or they get confused because you’re giving them information that’s not necessary for where they’re at at that particular point.
If somebody is just trying to use a feature, you don’t need to start throwing troublshoooting information at them. That’s too much information. They’ll get lost in the weeds.
It’s like feeding somebody a huge plate of food then they’re just tired and they want to take a nap. They don’t have time, at that point, to really digest it. They just going on.
Ledge: Right. You have to give people just enough to do what they were trying to do.
We talk about customer empathy. Everybody talks about that now. That comes up in every conversation I have, almost. It makes think, you have to be of the highest level of customer empathy of all the customers – internal, external – yet you need to kind of be assertive. Like, no, I know what you need at this point.
Ledge: I don’t want to hear what you think you need but I’m going to give you what is necessary to do the job that I know that you’re in at that particular time.
Christopher: You’ll always find out that you might be wrong, and you adjust for that. As a technical writer, you’re just trying to find the clearest path for your customer. Sometimes you’ll hear feedback. I’ve had say to me, “I think you’re assuming the customer knows more than they do.” That’s a valid piece of information. Sometimes I am., and it’s good to get that and then go back and look at what you’ve done and say, okay I see that, I can see that now.
I just finished writing the deployment guides for Azure, Google and AWS. That was quite an experience, to really think about those from a customer’s perspective and say, “Wow. This is hard the first time you do it.” All of these are very, very different. If you look at Google, it’s very simple to go through their UI, but it’s just poorly organized. Then you look at Azure and it’s really, really solid and polished, but it’s like walking through a maze to find what you need.
So everything has a little bit of a tradeoff in trying to figure this out.
Ledge: Yeah, and you have to consume everyone’s product – it’s not even just your own. I have to imagine, all of those companies are changing the way that you access X, Y, or Z and so you need to be aware of when everything else changes. They move one menu and your doc is out of date, and you don’t even know that.
How do you even take all the feedback necessary to move that forward?
Christopher: Well, I think you can reduce the need to do that sometimes, by rule number one, don’t document somebody else’s product. Hope that they’re not, because you don’t want to get in a position where you have to chase somebody else’s product development. You’ll spend all your time updating new documentation. You’ll never actually be able to do more with your docs. You’re just spending all your time going, “Well, let’s see. Did Azure change their UI today? Oh, they did. Great. Now I have to go back and change all my docs.” Where it’s much easier to say, “If you don’t know how to create an instance, go to this part of the Microsoft’s documentation and read.”
Ledge: Is there like a technical writer code of ethics? Like, if you’re going to change your docs, know that everybody else linked to it – kind of thing.
Christopher: You should. However, it doesn’t always happen.
Ledge: Do y’all get together for happy hour and be like, “Don’t change your URL.”
Christopher: Doesn’t happen. I wish it did. It would be so much easier.
I would say that, over my career, one of the regular occurrences is somebody coming and saying, “I’m getting a 404,” because some link has broken. Either your company changed their website and they reorganized it and didn’t alert everyone so some of your links now are broken and you have to get somebody to fix them.
Some companies have tried to fix that. Microsoft does a pretty good job by creating these relative links that never really break, and they do a pretty good job of that – or at least did when I was there. I left in 2007 or 8 – I can’t even remember now, it’s been a while.
Ledge: It runs together.
Christopher: Yeah. They kind of all run together. Some people try, they understand that dilemma, but the best thing is really to try to keep it as self-contained as possible and just send people to other places.
Microsoft does a better job of documenting their product. Tried it. Didn’t work on it. I did in development. It would be pretty remiss of me to try to document it the way that that company would do it.
Ledge: I’d say it’s a natural mistake. I think everybody in your seat sets out first to go, okay, you go here and you click this and do that. Then you quickly realize that that’s a fool’s errand because everyone is updating their product all the time.
Christopher: Right. Exactly.
Ledge: Which didn’t use to be the case. You could have plausibly years ago, documented somebody else’s thing and had a shelf life of a year before you broke it because it was Windows NT. But now you’re talking about like quarterly updates of major, major systems and often even more than that, when you’re talking about cloud systems.
Christopher: You never really know. They don’t announce a lot of it either, so you never really know until you go back in and say, “Wow, the menus have changed,” or, “The path to get here and the terminology has changed. I didn’t know that.” Not everyone puts out a ‘what’s new’ section to the contents so you can go through.
Ledge: Right. Release notes for content.
Christopher: You get stuck in that model of trying not to chase it as much as possible. There are very few real technical writer rules. That’s one of them; don’t document products.
One of them is, don’t promise anything. I know there’s always that need to say, “… and that feature will be in our next product.” That’s a no-no. The reason you never say that is you never know what’s going to happen in the future. Making a promise to a customer.
Ledge: Marketing and product will be kicking your door down there.
Christopher: Yes. Don’t promise. Marketing sometimes will do that. They’re forward-thinking. That is the purview of marketing. But in technical content you don’t do that.
Ledge: Those of us in the sales seat, we just make stuff up and sell it.
Christopher: Right. It’s completely different perspectives, and they’re different points in time. Somebody doesn’t need to be convinced once they’ve got the product. Technical documentation doesn’t need to convince people to use the product, it needs to tell them how to use it. Where marketing does need to convince, and sales does need to convince.
Ledge: There’s so much development now that documentation isn’t written all the time. We’ve got multimedia kinds of approaches. It comes so close to your support that the customer touchpoints become more and more embedded. Social media. Video. Documentation.
Your role feels like the kind of role that would just want to be expanded all the time. You get to inherit all the things that everybody else doesn’t want to deal with. “Oh, good, throw it to the technical writers.”
It reminds me. I was a distance runner and the way we would push back on everybody else would be, “Well, our sport is your sport’s punishment.” It’s similar to that. You have to have a great attitude about being a servant at all times.
Thirty years you’ve talked about doing this. Why and how have you got your brain there and just evolved with it?
Christopher: I think not making assumptions about what people want. If you talk to different people in your organization, they’ll tell you, “Our customers want more videos.” Which is true until they don’t want videos. Then you start hearing, “Well, why can’t I have web content?” You produce that and then you’ll hear, “But I want PDFs, downloadable PDFs as well.”
Sometimes you only can focus on one of those things, and you just have to do it and try to get to the others as you can but never making the assumption that it’s one thing, because it’s not. Most people want a combination of those things.
If it’s highly technical, a video isn’t going to do it because you don’t want to sit down and say, “Okay. At 3:06 that was actually some information I needed. So if I need to go back there I can bookmark that.” That’s easier, when it’s really technical, to put that kind of information in a guide that somebody can refer to. Technical documentation is reference documentation. It’s not learning specifically. It’s really more about, “I can’t remember how to do X. I’ll go look and find out what to do.”
Ledge: You must have a lot of SEO concerns. I mean, if you’ve got to make that searchable for whatever query someone might ask Google. Let’s face it. Google is the way that you find documentation now. If you’re beholden to so much of that – and that the number one hits for products tend to be documentation, which means marketing is all up your tail on, “Hey, you got to optimize that,” and, “Keyword-stuff that document, will you?”
Christopher: Well, depending on the industry – and the industry I’ve been in for the past 10 years which has been smaller startups that have very specific products – our documentation is not public. You have to own the product to access it. So it’s completely self-contained.
In fact, when I build my documentation, I actually build a static search mechanism that grabs all the keywords that I can manipulate. I can weight that any way that I want to get customers exactly what they need. Sometimes that works well, sometimes it doesn’t work so well. It just depends on how you approach it.
Ledge: Do you have your own support mechanisms, or people comment on the documentation where does that go? What is your continuous improvement loop?
Christopher: Well, being a small company, usually that’s support going, “I have a customer and they can’t find something, or they hate something,” – or they love something. Which is much less frequent because people generally don’t comment on things that are fine and help them, they focus on things.
Ledge: You must laugh. Every documentation system ends with that little widget at the bottom that says, “Was this helpful?” Thumbs up, thumbs down. How many thumbs up do you get?
Christopher: Usually it doesn’t happen. People generally don’t rate a thumbs up in any company I’ve worked for, but they will hit that thumbs down when they don’t like something.
The problem, there’s really no good way to tell, unless you’re really tracking your customer, what the problem is. For example, I could have clicked on a topic and went somewhere else from another link and done that three or four times and found what I needed. But I still gave you a thumbs down because it took me too long to get there. If you’re acting on that thumbs down at the end of that process, you’re actually fixing a topic that’s not broken, for example. That was the one that solved their problem, but they’re mad now because they had to click through 50 things to get there.
Ledge: They didn’t have, or didn’t take the initiative to write an open-ended comment that would actually have been helpful. “We expect you to be perfect, but we’re not going to tell you how.”
Christopher: That’s right. So you do the best that you can, and hopefully internally you take all the information you get. Customers will give you feedback sometimes. We’re small so we have a pretty good relationship with our customers because you can afford to do that when you’re smaller. As you get bigger, when you’re a Microsoft, you don’t have that luxury anymore – which is unfortunate but it’s just the reality of the situation.
Ledge: Okay. You’re talking to a lot of engineers right now and to a T most of them will tell you, “Oh, well I comment my code. My code is self-documenting. It’s so good.”
First of all, help the engineers, best practices from their standpoint – code, product, what have you – for arming documentation. Second of all, a lot of them are even smaller than what you’re calling small, and maybe have to put on the documentation hat sometimes and just don’t want to.
Let’s talk technical documentation for engineers. At least basic best practices and, if and when you have the benefit of finally having a big enough org that you can hire real technical writers, what should you have had in place best practice-wise in order to not leave those people with a disaster that can’t be rectified?
Christopher: Okay. Good question. That’s a long question.
Ledge: I like to talk.
Christopher: But easily answered. Number one, always think about your customer when you’re writing. Customers being able to understand what you’re saying the first time is the most important thing. Having to re-read something is deadly to any customer.
Also, don’t assume your customer has the level of knowledge you think they have. Always assume there are going to be people who are more technical who will probably gloss over much of what you’ve written, then you’ve got the other people that need more. Finding that balance takes a lot of time and effort. You aren’t going to get it right all the time and you’re just going to have to deal with that fact. Even after 30 years I still don’t get it right. Every audience is different and you have to play around with that until you find the sweet spot where you’re making the most people happy.
If you try to write to different audiences, you’ll find very quickly you run out of time to actually do that and you don’t really help anyone. You’re pigeonholing yourself and you’re running out of time and resources to do that. That’s another one of those things.
I would say, make sure that you have a good plan in place. One of the biggest mistakes people make is they don’t build a content strategy and an architecture to start with.
Architecture is hugely important. What tool are you going to use? You don’t want to get in a position where you have 15 little tools that you’re using and kluge this together all the time. Then you get really busy and you can’t maintain them any longer.
How are you going to know this? I use a structured authoring model called DITA, Darwin Information Typing Architecture. I use their build process which builds my content into various formats. It’s based on XML and XSLT.
So, I have a plan in place where I can write once and build all sorts of different documents out of that and conditionalize them for different audiences. That helps. It helps do more with less.
Always think about your architecture too because, when you get to the end game if you’re just using Word, for example, that could be tough. Let’s say you’ve got a user guide and you’ve got a deployment guide and there’s information in both and something changes. Now you have to go find all the documents that’s in and make the changes. Where, if you’re single sourcing your stuff, like I do, then I can deploy – I only need to change it in one place and I can deploy all my different pieces.
Ledge: Right. There’s a compiling and build process. Any developer is going to totally appreciate that. You have reference libraries and you have indexing, that data architecture is really the important metadata of your variable management. That you’d have all that.
Christopher: Think about your content in the types of content. Think about, you’ve got three primary types of content; conceptual content, tasks and reference. Writing them in a very compartmentalized way can be really useful because then you can get to the point where you’re just assembling the content to the documents.
Thinking about that as well. Thinking about it from a coding perspective. I mean, building modular documentation isn’t all that different from writing code. When you’re doing something like, for example, cross-referencing or including other pieces of content in a document, the system that I use allows you to contextually reference something into another document. It’s like an include file. The whole process is exactly the same. You’re taking information and making it available to the current doc from another document. So it only changes in one place and you can use it in a lot of different places.
The same thing with conditionalization of content. If-then. You’ve got different scenarios and you want different pieces of content to be outputs depending on the filter that you selected.
Building in that way can allow you to do a lot more with a lot less people, and that can really help especially when you’re really small.
Ledge: Yeah. It’s a lot to think about. I know a lot of developers who are solo or work with a couple of people, and documentation – to the extent that that exists at all – is going to be your README file in a repo. That’s not going to do any customer any good unless your customer is a hardcore open source dev and that’s how they roll.
It may be appropriate contextually, but it still doesn’t do all the things that you’re talking about. It’s a huge linear document for really non-linear, context-driven information.
Christopher: Some people want something linear, depending on what it is, some people don’t. Web is great for non-linear content because the entry point in web is search, where an entry point to a PDF, for example, is usually linear. You’re looking at the TOC and either reading through it sequentially, or you’re jumping to the part you want and reading through it sequentially. There’s different ways people consume information.
Again, it comes back you always want to keep in mind, people don’t like to read. It’s a necessary evil when they have a task to do. They just don’t want to do it. If you have a very complex process – and we talked about this much earlier before we started this podcast. If you have a task at hand and you’ve got your boss standing over your shoulder screaming at you, the last think you want to read is a bunch of conceptual information. Just give me the three steps to get this guy off my back. That is really the focus at that point and that’s what you really need.
So, writing in that way of thinking, what is the clearest, shortest path to solving my customer’s knowledge problem or a troubleshooting issue? If they just don’t know how to do something, just tell them. In technical writing, there is no such thing as too many bullet points. If you can make a bulleted list out of something…
Ledge: That’s very tweetable. Perfect ending. Thank you. It’s a social media world.
Christopher: No, I’m not going to take credit for that. I’m pretty sure I read that somewhere at some point.
Ledge: What do they say? If you copy one person, it’s plagiarism. If you copy many, it’s research.
Christopher: That’s right.
Ledge: Quick. Before we go, give a shout out to the company, Tempered Networks. You guys are doing some really interesting thing. I want to make sure that we just give a minute of information on that for any customers maybe in the audience for you guys.
Christopher: Sure. Probably the TL;DR version is, what we do is we make networking simple and secure. We do this by using a protocol called HIP, or Host Identity Protocol, as part of our much larger product and technology called IDN, or Identity Defined Networking.
What happens here is we solve what is a problematic issue for IP addresses, which is IP address contains identity and location. Our product separates those so you can create what’s called an identity based or identity defined network, which separates those two and allows access based only on identity.
So, location is unimportant in our system. For example, it allows you to roam around in different networks and still have exactly the same access you have, regardless of where you are. It frees you up in that way. Which is
It always blows me away when I see it. It’s like, you mean I can have a small app on my desktop and I can literally go to a coffee house and have exactly the same access and everything else?
Ledge: Right. There’s no VPN or… That’s a…
Christopher: No, no firewall rules, nothing. Just access. I can only see what I’m allowed to see. If some guy steals my laptop, he has a limited amount of information he can see.
A good example of that would be if you place – oh, let’s use an HVAC system behind one of our HIP services and it only is allowed to talk in the network to the reporting videos, for example. If a hacker gains access via that device on the roof on the building, all he’s going to see on your network is that reporting database. He can’t even see anything else. It’s completely cloaked.
Ledge: You can start to imagine, in a world where everything has an IP address, that this is a huge attach vector and that that level of technology would be super important.
Well, I’m glad you’re writing all this stuff about it. They’re blessed to have you.
Christopher: I hope they think the same thing. Sometimes maybe not. They’re like, there’s that guy, he’s making us think…
Ledge: Making us think, making us communicate. Man, this is tough.
Christopher, you’re fighting the good fight. This has been a fun conversation and thank you for joining us.
Christopher: You’re welcome. Take care.