Jeff Cross didn't plan to become a technical writer. He started a computer science degree, dropped out, spent a year trying to make it as a fiction writer, went back for a philosophy degree, considered academia, and then — almost by accident — realized that technical writing was the thing that made all of it make sense.

Now Senior Manager of Technical Writing at Arctic Wolf, Jeff has spent years doing some of the most complex content work in the industry: documenting third-party security integrations he has no direct access to, managing a full DITA migration while keeping up with release cycles, and pulling off a content carve-out from a corporate acquisition with translated content in three languages and a hard deadline.

In this episode, Jeff and Patrick talk about what it really means to do great documentation work, and why the hardest parts rarely show up in a job description.

They cover:

- Why the security space takes documentation seriously in ways other industries don't

- What happened when a product rename turned "a" into "an" across thousands of content files

- How AI helped a small team execute a DITA-to-DITA migration without outside help

- The checkbox doc that nobody wanted to write — and that way more people read than expected

- Why technical writing is less like writing and more like investigative journalism

Plus: Patrick discovers mid-conversation that Jeff was the person who fixed the BlackBerry email signature problem that drove him personally crazy for a year.

Hi. Thanks. It's great to be here.

That's great to have you. So I'm super excited to talk to you. You've had quite a journey through TechCom, um, and you're doing really interesting work today.

Uh, but before we get to some of the stuff that you're focused on in the present moment. Um, I love to just start with how you got into TechCom. I find this to be super interesting every time I ask the question. Um, so yeah, let's start there. What's your, uh, what's your background? How did you end up in this work?

And then did a co-op placement, which is like, kind of like an internship in, uh, in, in Canada. At some universities you can do like a school term and a work term and kind of alternate like that. I had a really bad, uh, co-op experience, um, that actually just led me to actually drop out of school afterwards for a while.

And I decided to do something as impractical as I could and, uh, and throw myself into writing fiction. So I spent a year working at that solidly and I was, uh. I mean, it's kind of embarrassing to think now, but I was naive enough to think like I could turn that into a, a career and earn a living writing fiction pretty quickly.

They were, uh, quite small and didn't really have very many technical staff, so I had this. Amazing opportunity to just do all kinds of things I didn't even know were specialized jobs. Like I did some QA and I wrote, um, functional requirements for developers and I did UX design and I, I did write some user manuals as well as part of that.

Um, that company ended up going. Uh, outta business, I don't think because of my work, but, but it happened, and that kind of aligned with me just trying to figure out what to do next. I went back to school again to do a master's degree in philosophy thinking, well, fiction didn't work. I still don't really like these real jobs, this like real world stuff, this practical stuff.

Um, and a bit of that, that job that I'd done, I had a lot of experience writing well from all the fiction writing I'd done, and I had this like capability from philosophy to take really complex. Abstract ideas and try to like boil them down to the essence and make that like clean and understandable. And when I looked at like the job market in our area and what did I want to do, technical writing kept popping up as like, this seems to fit with, with sort of what I've accumulated.

I probably got lucky then that there were several sort of jobs open at the time and I somehow managed to talk my way into getting hired at one of them. Had my first full-time technical writing job out of that. So that's, that's how I got started in the industry.

Oh, I love it. Uh, it's funny because, uh, one of my favorite people that I think is also for, is true for many of our customers.

So, um, I've seen it happen more than once. It's a, it's a good way in.

Yeah, it's, I'm not sure. I'd advise it as like, if, you know, you wanna be a technical writer, do philosophy first. But there's definitely, I think philosophy is a highly underrated area to major in. You learn a lot of, a lot of skills there that you can, you know, transfer to different things and definitely there's some, some applicability to, uh, to technical writing for sure.

You know, I've been convinced of that. The, I wouldn't have thought of it either, but there's a lot of structured thinking, there's a lot of writing, uh, there's a lot of having to prove your point and persuade people, and like those are all things that apply really, really broadly, especially in today's world.

Yeah, for sure.

Yeah, that's a tough question. I think, um, I think it took me a while, like my, my first job, um, was working for a company that made, uh, a, like a learning management system for most of our clients, I think were higher ed.

And so actually didn't. Feel like the work I was doing was that important there? I think it was, it probably was, but it was like hard to see it because, um, we were writing for audiences that wouldn't necessarily read it directly. It was, um, I think it departments at universities would often maybe use our material and repurpose it into their own branded materials to give to their own, you know, their own audience.

You know, the things I wrote at Blackberry probably have a, had a bigger audience than anything else I'll ever write just because the, the consumer base for that was so huge. Um, and, uh, you know, you start to talk to support and realize how many questions they get per month. If. That are repetitive and based on like how to information that could be covered up in the docs and things, and started to realize like the, you know, doing an effective job here, making this, this information find among stuff.

You might have to go into like a web browser on your computer to change your email signature. Or maybe you could do that from your phone in one area, or maybe you could do it in another area. And as I got digging into like user feedback, uh, on how to change my email signature, it was basically all like, these steps don't work.

This isn't what I'm seeing. Um, and I realized like when people are Googling for how to do this, they're ending up at this task that's in one of three completely different guides. It could be a guide for your phone, it could be a guide for like configuring your Blackberry internet service through your web browser or whatever.

And most of them were ending up on the wrong task, right? So we had. We had lots of, you know, you can imagine how frustrated someone is that they've got this blackberry and maybe like the signature says, like, sent from my Blackberry. They don't want it to say that anymore, or whatever. And they just can't A, figure out how to change it.

So if they read the wrong one first at least they knew where the right one was and it was there. And, uh, that. That made those like negative comments go away. The ratings of the topic went up, but also made me feel like, hey, I, like, I made a difference. Like it's kind of, you know, it's maybe a small thing, but it was a point of annoyance for thousands, like literally thousands of customers, right.

That I could help cover off by, by uh, re-architecting that documentation.

Um, I didn't have it for a super long time, but I loved it. Uh, and I remember trying to figure out how to change my email signature 'cause I'm super particular about that and I hate those things that say, sent from my iPhone, sent my Blackberry. That's really, really funny. Like, that's funny. That is such a wild connection.

Yeah.

Very cool. So you did some time at Blackberry, and Blackberry kind of transitioned from being. A phone company to a security company. Right.

Yeah. And unfortunately I was on the, uh, like the business was really, uh, quite split between their, the security and, um, enterprise focus. Mm-hmm. Um, and the sort of the phone consumer business.

And the, the enterprise side continued to iterate from sort of mobile device management, I guess they called it, into acquiring, making some security acquisitions and. Focusing there. Uh, funny story about how things like connect and come around the company I work for now, Arctic Wolf actually about a year ago, um, acquired, uh, most of the security products from Blackberry and folded them into Arctic Wolf.

So, so we had a bunch of staff come over from there that I used to work with, and, uh, a bunch of content that we had to figure out how to, like. Separate out from their CCMS and migrate over into our CMS and move across and, uh, all of that kind of stuff. So it's, uh, it's weird how these things go.

So, okay.

Yeah, and I think, so Blackberry made, uh, made a, a major, um, security acquisition of a company called Cylance and folded it into their core service.

And then last year. Uh, sold that off again to Arctic Wolf. So, so we acquired it and rebranded that as, um, uh, Aurora Endpoint defense and, uh, and made that part of our blackberry or Of Arctic Wolf offerings. Yeah.

Ah, got it. Okay. So you didn't actually go to cybersecurity through Blackberry. You went from Blackberry to cybersecurity.

Oh, fantastic. Uh, so I'm actually really curious about. Some of the nuances of technical content in the security services, but also technology space. Um mm-hmm. This is a space that's been growing really rapidly. Uh, it seems like it's a space that really cares about its content and the quality of its content.

Um, and, you know, for a lot of our audience, which is, you know, technical communicators, like that's interesting, right? Like a space that like has those interests. So, you know, what's been your observation? About technical content in the security, um, space?

That are, are different and that I appreciate are people take the content very seriously. It's, we don't get any of the kinds of comments I I've had at some other places, like who actually needs the docs or who reads this? Um. We get more the, can you improve the docs about this? Or how, you know, customers are finding this confusing.

We do a lot more, we have to go a lot further in actually documenting how to do things in third party products in order to be able to integrate them into our platform. Other places I've worked like Blackberry was basically like you just, you stopped writing when you got to the edge of your own product and you just, you left it to people to go figure out what to do in other products from that documentation.

But as you know, products have to work together and relate together. We find that. Uh, providing clear instructions. You know, if you're gonna integrate, integrate some third party product into our platform, here's what you need to go do in that product in order to get whatever, like a code or something that you're gonna share, or here's how to configure log forwarding in that product so that it, the logs get sent correctly to our sensor and make it back into our platform or whatever.

mm-hmm.

A, a big part of maintaining those docs is like trying to get rapid feedback loops.

When that content's not accurate anymore, a new version of that product has rolled out and the UI changed and the. The thing they needed to do is move to a different tab with a different name or something like that. And so being able to like hear about that quickly and respond to that quickly is, uh, is one of the challenges we have to, we have to face.

Wow, that's super interesting. So do you collaborate with those organizations at all or is it kinda left up to you to figure it out?

Yeah, not, not directly at all. Um, so it's, uh, if it, the best case scenario generally for us is there may be an internal lab that we can access, um, and get spun up. When I started we generally didn't have that, but that's gotten way better.

Um, but yeah, we're basically no direct contact and no, uh, not, not a direct partnership like that.

Wow. Wow. Interesting. It, it seems like that would be a, a place that would be ripe for collaboration. Um, that's super cool. So looking at, you know, some of the current stuff that you guys have done. Um, the integration stuff is really interesting.

What are some of the other things that you've been especially proud of, uh, that you guys have accomplished in the recent, recent history?

Um, that's a good question. I think, um, one of the projects that was, I guess, I guess the big, the biggest sort of. Um, changes for our team was migrating our, our content off of like one tech stack into another.

So we were writing all of that in Confluence. And then our external customer facing content, we were writing all of that using like a, a DOCSIS code tech stack. So writing in markdown, um, using GI for our, uh, our source control, and also triggering our publishing through a static site generator. And we moved all of that into dita, um, which was like.

A transformational project for the team to have to both like, you know, do that while we were still keeping everything up to date. And then get up to speed on learning the new tools and the new ways of publishing, learn data and, um, structured writing and everything while keeping. To all of our releases and everything like that.

So that was a big, that was a good test of like, we almost had to rerun content migration, but this time we were doing it from. One did a CMS into another. Um, so it was a big project again, like the, you know, the content had to like the work on updating the content for releases and everything had to happen.

Um, but we also had to figure out how to get the content out of the old system. How to, what did we need to modify to get it into, um, hereto and into our new system? What could we adjust? Like what did we have to adjust to get it to publish? What could we adjust around like branding or some light style changes?

So we kind of knew that our tooling ought to support that in theory, but we'd never actually run it through. Um. So we brought over English and then we had to figure out like, how do you, how do you bring the con translated content over as well? Um, so the folks working on that, um, again, like did an amazing job keeping everything going and doing that kind of on the side.

Um, and it went. I would say like a lot more smoothly than my worst case scenarios. Uh, we got it done on time. We didn't run in like we discovered issues as we went along, but we sort of dealt with them and nothing derailed the project or anything. And we were able to get everything published and then we were able to figure out how to do.

The process of folding in an acquisition or doing a merger with a content. Uh, it's always so nuts and like di da you know, there's like, there's a lot of like little things in there that can be.

Because like maybe they don't do it quite the way you do it, like maybe this in refactor. Yeah. But it's definitely better than like just totally two different formats.

Yeah, if we, like, when we did markdown to DITA and then Confluence to DITA was even crazier. Um, we, we ended up working with like a third party conversion company to do the content conversion to DITA for us.

So, uh, so yeah, that kind of helped us level up to the point where we could do the da da, da conversion, um, without needing outside help. It was still really hard. And I think one of the things I didn't realize is like, it would've been a lot easier in some ways if we'd actually just acquired all of Blackberry, because you could continue running their systems kind of indefinitely.

What, so looking back on that, if you could give yourself advice, you know, three weeks before you started that project, like what things would you tell yourself to look out for or, you know, try to do better?

Oh man, I think I really underestimated how much work that would be. Um, so maybe getting, getting a project manager earlier would've been really helpful.

I think for a while I thought, oh, well, we'll export the translated content from the other system and import it in, and then we realized later it's actually much better to just. Move over the English content, start a translation job with the same vendor, and have them run that through translation memory.

And then we, you know, that was actually, and then bring it back and import it into the new system was actually, was actually the right way to do it. Um, I think. I think another, I guess another thing I didn't realize, uh, ahead of time, the, fortunately the folks at Blackberry had really good discipline around like reusable content.

Uh, so you basically ended up like reviewing everything by hand and having to make changes outside the con ref as well. So that was more work than we expected. Um, yeah. And then I think, uh, I think like one of the, one of the big challenges in both migration projects I found was like. Uh, managing links between content, um, and just like how many of those links were, was hard to get them to link to the right thing in the new system.

And how many of those links actually were already broken in the old system and like nobody had realized it. Um, so it was hard to figure out like, what should they be linking to because they weren't working already. They're not working now after our test migration. So you need to go through and like, like figure that out.

So maybe I guess like budgeting some more time or just understanding what the approach was gonna be to some of those challenges.

There's always something that, it's just like the, the articles, right? Like, you wouldn't think of it, but it shows up and like you gotta do something about it. And it's such a big piece of managing these systems to get to a place where they're, they're really functional. Um, so in a lot of ways it's like development that way, you know, you always get a budget 50% more than you expect to spend.

Yeah, that's a good way of thinking about it. It's funny, it reminds me of a, an anecdote from Blackberry. One of the, um, more challenging things to produce there with the, on the phone side was like the, the printed legal material, the safety guide that you have to put in the, you know, in the box is usually legally required in different countries and.

On the critical path for shipping a phone to get this printed safety manual done because we were waiting for the final radiation results. And I remember one product, the lab stuff was behind schedule. Um, so we got the radiation results late and I was on a call with the, the product manager responsible for this whole program and basically like.

Very, very high risk that we're gonna be late shipping to market because you're waiting on printing these books, which are waiting on us providing the translated content and having the updated, uh, radiation numbers in it. And he couldn't understand why this was hard, right? He's like, why don't you just open Word and do a find and replace with the new radiation values?

But even that's challenging because like, um. You know, in, in English we use a decimal and a comma in a certain way, and in other languages it's like a comma instead of a decimal. And so if you don't realize that and you, you just copy and paste the English numbers across, it doesn't actually, it's actually an error.

Right. So, so even that kind of thing Yeah. Is, is complex. So there's reasons we set all of this stuff up. And then if everything kind of runs following the process, it's smooth. But when you have to like rush it or take shortcuts or anything, it's right. It's, it's really hard. And yeah, I totally agree.

People who haven't worked in that kind of system, just it's, it's really, it is really hard and it's really hard to understand why it's hard.

Yeah, exactly. Which, which would be, which would be a major issue. So then you would probably,

well

then you'd have like blocked shipments right at uh, when they, they they'd be looking at that, they'd be looking at the test results and say you've inaccurate data.

So, yeah.

Is there also, are the units presented always after, or are they presented before in some languages?

Oh man, I don't remember, but they're, they might be before You might be right about that. Yeah.

Yeah. That wouldn't surprise me. 'cause like a lot of times, like even when you have like semantic tagging around values, um, there's, the units will be programmatically added based on language because I think because of like the placement or something along those lines.

Yeah. Yeah, that's absolutely right.

Um, the other one that really catches people out with translation is, um, singular, plural. We had a, we had a big challenge at one point at Blackberry where, um. Some developers had, you know, hardcoded two versions of a string, you know, if there's one or if there's zero or more than one. And then it turns out in other languages they don't, they don't have the same distinction.

Right. I think I remember diving into that deep, and I think it was like maybe Russian has like 10 different possible. Agreement, like modifiers, depending on the number. And it's, it's really all kinds of categories that you don't even think would make sense, right? So you can't, you need to externalize all of that and have some system that manages the number of different strings and everything in different languages, or try to, or just avoid that altogether, right?

I feel like one of the things you realize when you start working in languages is just how simple English is.

Yeah, that's true.

So, um, you're, you know, the senior manager of technical communication, so you kind of get to define this, you know, what does great documentation mean to you at Arctic Wolf?

I think the, my intuition for what documentation should do in, in general Arctic Wolf or otherwise, is like, I, I generally think of it as like, people aren't reading it because they want to, they're, they're trying to do something else, and most people. Try to do that without having to use the docs. Um, if they do have to use the docs.

It's in service of like some other goal they have. If, if they're an end user, they're maybe trying to change their email signature so it stops announcing what product they own.

Yeah.

Um, so I think great documentation makes it easy for them to find the answer or the process to follow. And then makes that as clear and simple as possible so that they can complete their task or get the answer they needed to get unstuck and then, and then get back to what they were doing as, as quickly as possible.

So I think when you think of it like that, it, like a lot of other things fall out of it. Like you need good SEO for people to be able to find what they're looking for. You need well structured and organized information for people if they get close to, to figure out what do they need instead. Like the.

You just wanna, you know. Help them find it and then get them back outta the docs and on with what they're trying to do as quickly as you can.

Yeah, I would completely agree with that. And I think the recognition that Google is Tier Zero support. That, that's where your customers go to solve problems first.

And the more you can serve it there Yeah. Is, is really important today, in today's day and age. So I would, I would certainly highlight that. Um, so I'm just loving talking to you, but we also don't want to develop, develop a four hour podcast. Right. Um, so, um, so I wanna ask just a couple of fun questions before we go, you know, um.

First, if you could solve any problem in documentation or with documentation, what would it be?

In the same map that you're publishing, we can, we can move files and rename them and that works. But like, if you're linking to something that's outside the system, or you're linking to content that's in another map, um, there's, we still have the challenge of like, they get, they get broken. Like the other thing moves or it, uh, it.

The way you configure the link isn't correct. And so it shows up in the wrong place or whatever. If you're linking outside the system, like, you know this what was good one day is bad the next day. Um, and then on the other side, like when we have to, when we've had to, when we've moved content and like re-platform, how we publish things, we're working with stakeholders internally.

Um, that's, I don't know that there's so much time that's spent just like either

we do

time lost for customers following links that are broken or for people trying to go in and fix them and maintain them over time.

That's a, an ironic answer because I was just talking to someone before we got on to record this.

Uh, who's working on a detection system that will actually check external links as a part of the, the bill process. So, we'll, we'll, we'll talk later. We'll, we'll see if we can get that figured out for you at at least part of the, at least part of that. Um, okay, so I got another one. Before we ask our standard end question, what is the strangest, weirdest, or funniest doc you've ever had to write?

I don't know, timelines or whatever, they couldn't save the state of that. So it was gonna show you that box, like every time you log in. And there was a lot of concern that that would, uh, put people off. So I had to document basically how to sign in and check the box. Really more as like damage control.

Yeah. So it was like an announcement of the product. It was like, Hey, the sign in flow is changing. And then they needed something to link to. So I was like, okay, I'll throw this up here. It was like an unlisted documenta, uh, document. So you'd only find it through this link. And it basically said like, you know, what's changing is there's gonna be a box.

Really interestingly though, uh, I did go back and look at the analytics later thinking it would show like c Nobody read this. It was like medium. It wasn't nobody but it.

Wow.

It was quite a few people. It wasn't like a huge, a huge hit, but, uh, but actually way more people than I would've expected, at least actually visited that ridiculous saving document.

So, I don't know, sometimes just, uh, having some humility and going along with it is maybe the best thing to do.

Oh gosh, that's almost like an, it's almost like documenting an apology.

Yeah, it was, it was essentially like a, yeah, like a damage control doc. Like, you know, we're sorry this, this has to be here like this.

But

And in that situation, you know, building the database table and linking it all up and all that stuff on that release probably was less valuable than whatever else. And so what do you do to.

Yeah,

it's almost always documentation.

It's true.

Okay. Yeah.

That's a really, that's a great point about trade offs.

I think a lot of people don't, it's easy to look at one thing and say, why couldn't this have been better? Right. And not see the opportunity cost of that. Like, well, if we spent more time on that, we wouldn't have been able to do this other thing. Right.

Yeah. That is, that is software in a nutshell.

Yeah.

Okay. Um, yeah, that's a really good question.

I'm not, I'm not sure what the best thing to say for that is. I think, um, a couple things that come to mind, like obviously. Working on writing skills is, is really key. Um, but I think maybe realizing like actually hands-on keyboard writing is, uh, probably gonna be less than half of your time. Like, uh, like I've fairly recently heard this comparison of like, technical writing is more like journalism than many other kinds of writing.

Sometimes depending on how well sort of organized your, your dev team is, you may be doing a lot of that work just to try to figure out what's releasing when, and somebody might tell you one thing and somebody else tells you another, and figuring out who, who actually knows the answer to that. Once you do your writing, then you're gonna have to get people to review it and like either, you know, formally sign off or informally give you a thumbs up or whatever.

So chasing them, building soft skills so that you can establish good relationships with the people you're gonna be dependent on. To get all of that done, I think is as important as the sort of the core writing skills. So maybe that's, uh. Maybe that's a piece of advice I'd give is like, you know, go in with your eyes open about that and uh, and think about developing skills on both sides kind of equally.

Yes, that's right.

Jeff, it has been an absolute pleasure having you on today. Thank you so much for coming and sharing your story with us.

I'm behind the docks. Um, I look forward to seeing you in the future out in the TechCom community.

Okay, thanks very much. It was fun.