Sometimes Dragons

The Docs Are In: Tech Writing & Jigsaw Puzzles

Share via Twitter Share via Facebook Share via Linkedin Share via Reddit

I love a good “How I got into tech” origin story. I am also here for any and all conceptual frameworks that help folks in the tech industry become better communicators and collaborators. I was fortunate to get a little bit of both in a recent conversation with Ember Stevens (who is currently a technical writer at LaunchDarkly) as part of our The Docs Are In series.

As Ember explains, she (like myself and my colleague Kate Holterhoff) ended up in tech by way of higher ed:

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.

Fun fact: it was only after we stopped filming that I learned that Ember’s sojourn in higher ed also included a graduate degree: she holds an M.A. in Information Science and Learning Technology from the University of Missouri-Columbia.

We also spoke a bit about the differences between being the lone tech writer at an organization vs. working on a team, as well as some of the current docs workflows Ember participates in while working (on a team of three) on LaunchDarkly’s technical documentation:

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 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 of documentation and PR into GitHub. And then typically our tech writing team takes over from there.

As you may be able to tell from Ember’s description of LaunchDarkly’s workflows, her team employs a number of docs-as-code (or docs-like-code) processes. While there are many benefits to such processes, they can also add another layer of onboarding overhead for anyone looking to get into tech writing. As Ember notes:

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.

To my mind the time spent in learning these processes can benefit tech writers both in their own career paths (as familiarity with version control, ticketing, and CI/CD systems can transfer nicely to other roles and organizations), as well as in affording them ways to work with more technical subject matter experts (SMEs) using tools and processes with which those SMEs are likely already familiar.

And now we get to the jigsaw puzzle part of the conversation. I first met Ember in June at cdCon 2022 (a conference organized by the Continuous Delivery Foundation), where she gave an excellent lighting talk, “Technical Documentation is Like a Jigsaw Puzzle”. In the talk Ember compares pieces of advice for anyone looking to get started with technical documentation to some of the techniques she uses in solving jigsaw puzzles. While you can watch Ember’s cdCon talk in its entirety here, Ember was also kind enough to recap some of her advice during our conversation.

My absolute favorite comparison: framing (literally) the act of creating a documentation outline as similar to the act of piecing together the edges of a jigsaw puzzle first.

The text "creating an outline" next to an image of a jigsaw puzzle with the puzzle edges completed and the puzzle box in the center.

One thing (among many) I learned: jigsaw puzzle experts do not always start with the edges:

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.

This made me realize that as much as I am a proponent of outlining, it is not always something I do myself, especially when I am in a rush or working in a medium with which I am familiar. Although this is usually fine, I do wonder if I am sometimes making the act of writing more difficult by skipping this step. And so for this post (the one you are currently reading) I a) absolutely made an outline and b) had a much easier time writing than I have on other occasions. That may, however, be partially attributed to how fun this conversation was to film and to write about.

You can watch the video of my conversation with Ember below or see the full transcript and related links here.

Disclosure: the Continuous Delivery Foundation (CDF), GitHub, and LaunchDarkly are RedMonk clients; however, this post and the RedMonk video mentioned in this post were not commissioned by any entity.

No Comments

Leave a Reply

Your email address will not be published. Required fields are marked *