{"id":430,"date":"2022-09-06T12:49:17","date_gmt":"2022-09-06T16:49:17","guid":{"rendered":"https:\/\/redmonk.com\/kfitzpatrick\/?p=430"},"modified":"2022-09-06T12:49:17","modified_gmt":"2022-09-06T16:49:17","slug":"the-docs-are-in-tech-writing-jigsaw-puzzles","status":"publish","type":"post","link":"https:\/\/redmonk.com\/kfitzpatrick\/2022\/09\/06\/the-docs-are-in-tech-writing-jigsaw-puzzles\/","title":{"rendered":"The Docs Are In: Tech Writing & Jigsaw Puzzles"},"content":{"rendered":"

I love a good \u201cHow I got into tech\u201d 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<\/a> (who is currently a technical writer at LaunchDarkly<\/a>) as part of our The Docs Are In<\/a> series.<\/p>\n

As Ember<\/a> explains, she (like myself<\/a> and my colleague Kate Holterhoff<\/a>) ended up in tech by way of higher ed:<\/p>\n

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\u2019s kind of how I got my start.<\/p><\/blockquote>\n

Fun fact: it was only after<\/i> we stopped filming that I learned that Ember\u2019s 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<\/a>.<\/p>\n

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\u2019s technical documentation<\/a>:<\/p>\n

I\u2019d like to think that we have a pretty polished workflow. And of course, it\u2019s different depending on what sort of documentation we\u2019re writing. In general, if we\u2019re documenting a brand new feature, so something that\u2019s new and something that customers haven\u2019t used at all yet, we\u2019ll actually work with our engineering teams and ask them to write first draft documentation, and we don\u2019t 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,\u00a0 just so that we have a baseline to work from. And then from there we manage all of our workflow in GitHub. So it\u2019ll usually actually start with a ticket in a piece of software called Shortcut. And so we\u2019ll 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.<\/p><\/blockquote>\n

As you may be able to tell from Ember\u2019s description of LaunchDarkly\u2019s workflows, her team employs a number of docs-as-code (or docs-like-code<\/a>) 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:<\/p>\n

I have worked in roles that didn\u2019t 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\u2019re like myself and you\u2019re coming from somewhere that didn\u2019t use that whole tooling process, you have to not only learn all about the product that you\u2019re 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.<\/p><\/blockquote>\n

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.<\/p>\n

And now we get to the jigsaw puzzle part of the conversation. I first met Ember in June at cdCon 2022<\/a> (a conference organized by the Continuous Delivery Foundation<\/a>), where she gave an excellent lighting talk, \u201cTechnical Documentation is Like a Jigsaw Puzzle\u201d. 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\u2019s cdCon talk in its entirety here<\/a>, Ember was also kind enough to recap some of her advice during our conversation.<\/p>\n

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.<\/p>\n

\"The<\/p>\n

One thing (among many) I learned: jigsaw puzzle experts do not always start with the edges:<\/p>\n

I always, when I\u2019m putting together a puzzle, I always put together the edge pieces first and I\u2019m 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\u2019t put together the edge first. Like that\u2019s that\u2019s a pretty standard technique. But eventually you can get so good that you actually can start working on pieces. So that\u2019s really impressive. I\u2019m not there yet, but yeah, generally I always go for the outline.<\/p><\/blockquote>\n

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.<\/p>\n

You can watch the video of my conversation with Ember below or see the full transcript and related links here<\/a>.<\/p>\n