RedMonk’s Kelly Fitzpatrick and Ember Stevens (Technical Writer, LaunchDarkly) discuss technical writing and documentation (docs as code; what it’s like being the lone tech writer at an organization vs. working on a team; working with SMEs) as well as their respective tech industry origin stories in public higher education. Ember also shares some tips on how to get started with technical documentation–tips that mirror approaches to piecing together jigsaw puzzles.
This was a RedMonk video.
Disclosure: LaunchDarkly, GitHub, and the Continuous Delivery Foundation (CDF) are RedMonk clients; however, this video is an independent piece of work and was not commissioned by any entity.
Rather listen to this conversation as a podcast?
Resources
- Ember’s excellent cdCon 2022 Lighning Talk, “Technical Documentation is like a Jigsaw Puzzle”
- LaunchDarkly’s technical documentation
Transcript
Kelly Fitzpatrick: Hi there. I’m Kelly Fitzpatrick with RedMonk. Welcome to The Docs Are In. Today we’ll be talking about documentation, technical writing, and jigsaw puzzles. Joining me to talk a bit about how all of these pieces fit together is Ember Stevens, who is a technical writer at LaunchDarkly. Ember, could you please tell us a little bit about who you are, what you do, why you care about documentation?
Ember Stevens: Thanks, Kelly. Like you said, my name is Ember, and I currently work for LaunchDarkly, which is a business-to-business feature management software company. So I spend my days writing technical documentation mostly about how our UI works, but also SDKs and our API and just sort of other things that come along as needed.
My background is actually in higher education, so I worked for a state university for several years, and I eventually made my way to the admissions office for the graduate school there and was managing their admissions software. And then I transitioned to working for that vendor. And while I was working for that vendor, I found out about tech writing and I was doing a lot of tech writing myself in my role and helping train folks on our software there. And then once I found out I could do it full time, I said, Oh, hey, this sounds really cool. So I was really fortunate to be able to get into a tech writing position there, and that’s kind of how I got my start. So not necessarily a traditional tech background, but the higher ed background has I think, been really helpful for me in a lot of ways.
Kelly: Yeah, I think that’s a great “How I became a tech writer” story and if it helps, I also come from a public research university background. So I’ve worked at the State University of New York at Albany and also Georgia Tech and then ended up going into the tech industry. So I feel like a lot of people in the tech industry have what they would consider a non-traditional tech background and yet end up here anyway. So yeah, it’s very cool. So, so getting back to the kind of tech writing work you do and you’ve spoken a little bit about the type of technical documentation that you work on at LaunchDarkly. Can you talk a little bit about the workflows that go into producing that documentation?
Ember: So I’d like to think that we have a pretty polished workflow. And of course, it’s different depending on what sort of documentation we’re writing. In general, if we’re documenting a brand new feature, so something that’s new and something that customers haven’t used at all yet, we’ll actually work with our engineering teams and ask them to write first draft documentation, and we don’t expect anything polished or fancy at all. We just want the engineering teams to sort of get down how they use the feature, how they expect customers to use it, what it can do, just so that we have a baseline to work from. And then from there we manage all of our workflow in GitHub. So it’ll usually actually start with a with a ticket in a piece of software called Shortcut. And so we’ll start with our ticket and then either the engineering team or someone else will write a first draft documentation and PR into GitHub. And then typically our tech writing team takes over from there.
If it’s not a new piece of functionality–so maybe there’s just changes to something that’s existing or maybe visual changes to the UI, a lot of smaller type stuff–we don’t expect engineers or other folks to do that. That’s really in our realm. So we’ll work with whatever engineering team is, making the changes, talk with them. Sometimes we’ll go to their meetings or we’ll scheduled something in particular, like an individual meeting with them to find out more about the changes. And then we’ll make those changes ourselves. Again, working off of the Shortcut ticket. PRing into GitHub. And, and then we add our viewers sort of just depending on if it’s a real technical change, maybe we’ll have an SDK expert come in and look at it. If it’s something that we feel like we have a handle on, then we’ll just ask another writer to review it from the team and then we’ll publish from there.
Kelly: I always love when documentation processes are kind of like “and we’re just going to start with GitHub,” especially when you’re bringing developers in. It’s kind of like, “hey, we’re working with tools that are at least familiar to developers at some point.” What role does docs as code (or docs like code) play into your kind of current processes?
Ember: Yeah, I think it serves a couple of different roles. I think, like you said, it does make it a little bit easier for some of the engineers and developers to work with our processes because it is tools that they’re familiar with. We also, you know, we host our own docs on our own website. So we really we have everything that’s controlled through GitHub. So any any sort of changes we’re making even on the back end, all of those go through the normal process and GitHub. And so I don’t know, I think it’s a good way to keep things sort of controlled and make sure the right reviewers are looking at the right changes and that sort of thing. I have worked in roles that didn’t sort of follow the docs as code framework and it has advantages and disadvantages. Although I like it, I think that there can be a bit of a learning curve. So if you’re like myself and you’re coming from somewhere that didn’t use that whole tooling process, you have to not only learn all about the product that you’re now writing about, but you also have to learn how to use the internal tools. And there can be a little bit of a ramp up there.
Kelly: I feel like that could be intimidating for some people, but also I feel like once you’ve put in the effort to learn those tools, I feel like they could transfer to other things very, very nicely. So it could be an investment in what you might want to know just in the industry in general.
Ember: Yeah, yeah. I’m really glad that I had to learn for the role I’m in now, because I also think it makes it a little bit easier to talk with folks in other teams that are using those same tools every day because we kind of have the same sort of background, language, terminology. And so I think it makes a difference.
Kelly: Yeah, absolutely. So my understanding is that you have at some point been the only tech writer in your organization, and now you’re working with a team and a whole bunch of other teams in terms of dealing with subject matter experts from time to time. What are some of the differences from being that kind of sole tech writer to working with a team?
Ember: You know, when I was a sole tech writer, there’s advantages and disadvantages, but I definitely think I prefer the team. When I was working alone, you know, I had full control over the information architecture. I decided what went in, what comes out when it gets published. And in some ways, that was was satisfying to get things set up in a way that I felt was logical and made sense. And I was doing a lot of organization and sort of clean up from previous folks that had contributed here and there to that knowledge base. But it was also a little bit lonely and it was sort of difficult when you don’t have someone else to bounce ideas off of and go to and say, “Should I say it this way or this way? Do you think this should this be organized like this or like that?” And it also sometimes felt like people valued the work that I did, but there wasn’t anybody else there that really understood what I was doing. And so it was sort of like, well, just give it to the tech writer and I’ll figure it out. And I don’t, you know.
Kelly: They’ll do some wordsmithing and it’ll be magical and then we’ll have, we’ll have some documentation.
Ember: And there wasn’t a real clear editing process or understanding of who had the authority to edit this, because it was just me. So sort of handling when somebody over here says, “I think we need to make this change.” And somebody over there says, “I think we need to make that change.” And reconciling those could be challenging sometimes. So transitioning to working on a team–and it’s a small team, there’s three of us. But even that, it makes for me a really big difference to be able to have just a couple of other folks who we can talk about issues, and we meet every week to kind of go over what we’ve been working on and plan out the next week, and I really enjoy that.
Kelly: Yeah, it definitely makes collaboration different when you’re collaborating with folks who are doing something very similar to what you’re doing, even if you’re not all doing the exact same thing at any given moment.
I want to make sure that we get to the the jigsaw puzzle part of our conversation. And so I met you at cdCon a couple of months ago and you gave this amazing lightning talk–and I’m going to make sure I read the title–“Technical Documentation is Like a Jigsaw Puzzle.” And first of all, lightning talks are in and of themselves amazing, because saying something in 5 minutes is so much harder than I think anyone understands that it is. But the talk itself, I thought, was great. And in it you talk about putting together jigsaw puzzles, which you have much more experience in than I do, but also how that translates to somebody who is perhaps trying to figure out how to begin doing technical writing, even if they’re not necessarily a technical writer. Can you just speak a little bit about that and we’ll put a link to that talk here for folks who want to go and catch it. But some of the highlights of that, especially in terms of anyone out there who’s watching, who is like, “Where do I go? What do I do if I want to get started with tech writing?”
Ember: Yeah. You know, I’ve always really enjoyed jigsaw puzzles. It’s sort of an activity that my family always did, and we’d have family reunions and get out the puzzle and everybody work on it together. And so I started thinking about it in terms of technical documentation and the way that we kind of sort and organize data, whether it’s puzzle pieces or whether we’re writing about something. And I noticed that there are some people that really dislike jigsaw puzzles because it’s so overwhelming. Like they open up the box and they say “forget it.”
Kelly: Like just 3000 pieces–ugh!.
Ember: Yeah, like where do you even begin? You know, so and I think that a lot of people understandably feel the same way about technical documentation. So maybe they’re an engineer or a developer or in some other role and even a project manager. And they know that they’re supposed to be writing about how something works, but it’s just a lot of information to distill down into a short piece that’s supposed to be clear and concise. So I started sort of seeing correlations in the way that you kind of take things step by step. You want to know what goal you’re working toward and having steps that you can follow to help you sort and organize your thoughts. Yeah, I think that’s kind of where the similarity started.
Some of the things that I talked about was you sorting your pieces. So instead of being overwhelmed by the huge pile, you can start thinking about the red pieces over here, the blue pieces over here. This has a weird texture on it that’s going to go up there. And and you can think about technical documentation in the same way when you’re thinking about like, “What are my angles? What are some common themes here? And what am I going to actually end up communicating to the reader?” And then working through building an outline. So just like you pull out your edge pieces with a puzzle and put them together, creating an outline for yourself can just sort of help guide you and make you not feel necessarily so overwhelmed by the blank page. And then I also talk about getting an editor, and that doesn’t necessarily have to be another writer or a capital “E” Editor. That can really can be anyone that has some familiarity with what you’re doing. So maybe it’s somebody from the engineering team or maybe somebody from marketing or just in the way that like getting help with puzzle pieces. Sometimes you’re looking or looking and you just can’t see the relationship and someone else can come along and say, “Oh no, that goes right there.”
Kelly: Let’s get some fresh eyes on this problem.
Ember: Yeah, yeah. And that’s so valuable when you’re writing. Even when you’re a good, experienced writer, there’s always going to be something that someone else is going to catch that you don’t. And so you’re going to end up with a better end product.
Kelly: Yeah, absolutely. And for me, I think the visual that I take away from [the talk] is the idea of the outline as putting the kind of edges of the puzzle together. Like I had never thought about it that way before. And I love outlining. Like, I think outlines are great. Oh, man, this is like a really good both visualization and explanation for why why would you make this part of your process at all.
Ember: Yeah, it’s funny. I always, when I’m putting together a puzzle, I always put together the edge pieces first and I’m really into competitive jigsaw puzzling and I read about it. And so I saw somebody talking about how real experts, people who puzzle competitively, they get to the point where they actually don’t put together the edge first. Like that’s that’s a pretty standard technique. But eventually you can get so good that you actually can start working on pieces. So that’s really impressive. I’m not there yet, but yeah, generally I always go for the outline.
Kelly: Excellent. Well, this has been a great chat. Thank you so much for taking the time for speaking with us today.
Ember: Yeah, thank you. I enjoyed being here.
Kelly: Excellent. And with that, the docs are out.
