Continuous Delivery Foundation cdCon 2022, 24 Jun 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Lightning Talk:Technical Documentation is like a Jigsaw Puzzle - Ember Stevens, LaunchDarkly

Description

For more Continuous Delivery Foundation content, check out our blog: https://cd.foundation/blog/

Lightning Talk:Technical Documentation is like a Jigsaw Puzzle - Ember Stevens, LaunchDarkly
JW Grand Ballroom 2

Speakers: Ember Stevens
Assembling a jigsaw puzzle is a combination of science and art. There is a method to sorting the pieces, assembling the frame, and completing sections in a logical progression. Much like staring at a pile of 500 unsorted cardboard puzzle pieces, the blank page can be overwhelming when trying to write technical documentation. Where do you start? What should you focus on? What do your readers even need to know? Documenting your work is an essential part of the development lifecycle, but if you don’t write regularly as part of your job, it can feel daunting. Luckily, there are established methodologies you can lean on whether you’re trying to make sense of your puzzle pieces or write down how your code works. This talk will explore what Ember has learned from assembling countless jigsaw puzzles over the years and how it applies to writing technical documentation.

A

Hello, everybody. Thank you so much for coming today to my lightning talk. My name is ember stevens, and I'm going to be talking to you today about how technical documentation is like a jigsaw puzzle, so a very quick overview of the agenda. First, I'm going to tell you a little bit about who I am and why I care about this, and then I will talk you through some of the ways that I find writing technical documentation to be similar to putting together a jigsaw, puzzle and, finally I'll talk about the importance of getting help.

A

So, first of all, what is this? Who am I and why do I care? Well, I am a technical writer for a company called launch darkly, and I spend my days writing about feature management software, but I'm also a lifelong puzzle. Enthusiast and I actually competed in my very first jigsaw- puzzle competition on the national scale in april. So it's something that I enjoy a lot before I get into it. I want to highly encourage you, if you're interested in writing technical documentation to check out this book doc for develop docs for developers.

A

A lot of the ideas from the book are in this talk and I think it's it's a really great resource.

A

Okay. So how are technical documents like jigsaw puzzles? Well, there's a lot of the same techniques that I use whenever I'm putting together a puzzle that I use whenever I am writing technical documentation.

A

So, in both cases I like to sort and organize my data before I start.

A

I then like to create an outline I like to start with the easy stuff and end with the hard stuff, and I always try to get help when I need it: okay, sorting and organizing, when I first dump out my puzzle pieces on a table, I sort them all by color and pattern and try to sort of get an idea of what picture I'm working with here and kind of where I need to go from there with my data.

A

So when I'm writing technical documentation, I kind of do the same thing and when I'm sorting my data and getting ready to write something. I approach this with sort of two ideas in mind. So one is, I think, about content type. What sort of content do I need to write, and the second is what are the readers goals and needs?

A

So first is content type. There are lots of different technical documentation, content types- and these are just a few uh but, for example, um there's conceptual documentation which is kind of big picture overview uh conceptual the feature, something like that. There's reference documentation, those are things like glossaries, maybe an api reference. Typically, it's documentation that you don't expect the reader to read top to bottom. They just kind of come in and out as they need it.

A

Another common type is procedural documentation and this is like tutorials and numbered how-to's, and I'm going to use this in my example, because it's what I spend the majority of my time writing about at work.

A

All right so after you choose your content type, the next thing to do is think about what are your readers goals and needs. You do not want to write everything you know about your feature. That is too much information for the reader and they're not going to care about a lot of it. So you want to introduce the reader to what is the feature?

A

How does it solve their needs and how do they actually use it?

A

Okay, so once you've sorted all of that out. The next thing that I do is create an outline.

A

So whenever I'm putting together a puzzle, I always pull out the edge pieces and build the frame first, and that gives me a really good idea of what to expect going forward, and there are people that put together jigsaw puzzles that don't do the frame first, but I try not to be friends with those people all right, so I'm creating an outline for my doc in this example, is a procedural documentation outline so first, I want to include an overview. So what is the feature and how is it going to meet the reader's needs?

A

Second, is I want to include prerequisites, so this might be something like if the reader needs an api token before they get started, or maybe they need administrative level access in your app. You want to put it in here and the last part of the documentation is procedural, and so this is the numbered step-by-step, very basic one action item, percep per step: here's how you accomplish the task.

A

Okay, so now that you have your outline in place, it's time to actually start writing, and um likewise, whenever I'm putting together a puzzle, I kind of pick out the easy parts, the the pieces that obviously go together and I put those together first because it gives me some momentum and kind of makes me feel like I'm making progress and that um that I'm going to be able to finish this this puzzle.

A

So likewise, whenever you're writing, I recommend start with the easy parts start with the parts that you know.

A

You don't need to write an order so often I'll write the step-by-step procedural part first, because that's the easiest part for me and sometimes I'll write the overview last once I kind of figure out uh what I'm actually talking about and when it comes down to it, when you kind of get down to the end and you're starting to get stuck. This is a good good time to get help.

A

Sometimes, whenever I'm putting together a puzzle, I'll put I'll put two pieces together and I'll look at them and I'll think I I think these go together, but I can't actually really tell, and so having a friend come in and tell me no, those don't actually go together is really helpful. So everybody needs an editor. Not everybody is lucky enough to have a built-in writer. Maybe you don't really know who you can work with on your team, but sometimes just getting another reviewer.

A

Even if it's not a professional writer to look at it is really helpful. Sometimes folks from other departments like marketing to be help can be helpful um in any case. Having that final set of second set of eyes on your documentation is guaranteed to make it better.

A

So that's my lightning talk about how technical documentation and jigsaw puzzles are alike. Thank you very much for coming and if you have any questions for me I'll be around after here and online.