& more

Episode 08

Why Should You Write Technical Documentation?


Show Notes

We’ve all encountered technical documentation: Readmes, product manuals, and how-to guides, to name a few. Some are good, some are not so good, and some are less than helpful. Open source communities often need more people to write and update their projects’ documentation—but it’s not an easy task. So why not help out?

In this episode, we find out why everyone should write at least a little bit of technical documentation. We speak to people who contributed to documentation to help, to learn, and even to start their careers in open source.


00:03 - Johan Philippine

Brent, Angela, today, I want to talk to you about your experiences trying out open source software.

00:13 - Angela Andrews

Brent, would you like to go first? Because my experience is probably going to be wildly different.

00:20 - Brent Simoneaux 

I don't know about that. Okay. Well, let's see. So most recently, I was trying to get some network mapping software to run. And I'll be honest, it was pretty disorienting. I had a lot of trouble finding my bearings when I was first getting into it.

00:37 - Johan Philippine 

What did you end up doing?

00:39 - Brent Simoneaux 

Honestly, I got frustrated and just left. I shut my computer down and I just stopped.

00:46 - Johan Philippine

Oh, no. Angela, you seem like you're more of a pro at this. What do you do to get your bearings with a new piece of open source software?

00:54 - Angela Andrews 

If you've never used it before, I usually go to the website, to the documentation page. How do I use this? How do I plug this into my current existing code? Because sometimes it's just not that obvious. You want to make sure that you're using it properly, so documentation is really important.

01:14 - Johan Philippine 

It really is. But in my experience, it's not always very good. I mean, the goal of documentation is to help people understand how to use the program. But if it's not written well, then it's not doing its job.

01:30 - Brent Simoneaux 

Where does documentation come from though? It seems like a pretty specialized skill to me. Who writes documentation?

01:39 - Johan Philippine 

Well, Brent, that's today's question. Why should you write technical documentation?

01:45 - Brent Simoneaux 


01:45 - Johan Philippine 

Mm-hmm (affirmative).

01:46 - Angela Andrews

Yeah, you.

01:48 - Johan Philippine 

You too, Angela.

01:49 - Angela Andrews 

Oh, yeah. Me.

01:50 - Brent Simoneaux

Yeah. You're not getting out of this.

02:00 - Angela Andrews 

This is Compiler.

02:01 - Brent Simoneaux 

An original podcast from Red Hat.

02:04 - Angela Andrews 

We're your hosts.

02:05 - Brent Simoneaux 

I'm Brent Simoneaux.

02:06 - Angela Andrews 

And I'm Angela Andrews.

02:08 - Brent Simoneaux 

We're here to break down questions from the tech industry, big, small, and sometimes strange.

02:15 - Angela Andrews 

Each episode, we go out in search of answers from Red Hatters and people they're connected to.

02:21 - Brent Simoneaux 

Today's question, why should you write technical documentation?

02:28 - Angela Andrews 

Producer Johan Philippine is here to help us out.

02:32 - Johan Philippine 

So we're going to talk about why you should write technical documentation. And the first reason is that it's a really in-demand skill in the open source community. I mean, one of the things that we constantly hear about in the community is how many projects are in almost desperate need for people to write the technical documentation.

02:56 - Brent Simoneaux 

I also feel like it's an opportunity that doesn't get a lot of attention either.

03:02 - Angela Andrews 

Yeah. It's not the sexy way to get involved, if that's such a thing.

03:09 - Johan Philippine 

Every now and then, we'll hear someone say, "Oh, the best way to get into open source and to start contributing is to do documentation." We spoke with Matthew Miller, he's the Fedora project leader. And he really went into a lot of detail as to why these projects have such a deep need for documentation.

03:30 - Matthew Miller

Documentation is always vital. There's a constant need to keep up with things, and there's always new things to explain.

03:38 - Johan Philippine 

I think that starts to get at why this is such a persistent problem. I mean, it's often a Sisyphean task.

03:47 - Brent Simoneaux 

We're pushing boulders up a hill.

03:48 - Johan Philippine 

Exactly. You push that boulder. I mean, it's a lot of work. You push up that documentation boulder up the hill. But almost as soon as you document and publish it, it's already out of date, so that boulder just goes right back down the hill and you gotta start over again.

04:04 - Brent Simoneaux 

And I imagine, I mean, this is difficult, I think for any project. But the Fedora project, I mean, that is a big open source community, right?

04:15 - Johan Philippine 

That's a huge one, yeah. And I believe they have two updates a year.

04:21 - Brent Simoneaux 


04:21 - Johan Philippine 

Is that right?

04:22 - Angela Andrews

That sounds about right, yeah.

04:23 - Brent Simoneaux 

Yeah. That's a lot.

04:25 - Johan Philippine 

It's a lot and it's a big project, so there's a lot of stuff to document. Now, the other thing that makes it difficult is that a lot of these open source projects are led by volunteers. And more often than not, they're contributed to by developers.

04:42 - Matthew Miller 

So I don't want to underestimate the number of people who aren't from an engineering background working in the project, but the general sense is it's pretty low. So if you look at a company like Red Hat, which is, I don't know, 15,000 people give or take, there's a couple thousand engineers. And then just a vast majority more of people who are in all the roles that are around, even though Red Hat is a technical company, around the roles that go around that from sales to support, to marketing, to design, to documentation, just everything, all the other infrastructure you need to make a company work.

05:19 - Johan Philippine 

On top of that, it's fairly rare to find people who are really good at two completely different skill sets.

05:28 - Matthew Miller 

I think ultimately, writing documentation and programming, or system and administration, are just very different skill sets. And people can be good at both things, but it's not automatic. So someone who's not necessarily good at writing in a concise way that communicates to end users, might be really, really good at implementing clever solutions to a programming problem, or making sure the infrastructure is up and running reliably.

05:58 - Brent Simoneaux

Yeah. I see what he's saying there. Just because you're a good programmer, doesn't mean you're a good writer.

06:04 - Johan Philippine 

Right. And I'm a writer. I'm going to go ahead and say that I'm a fairly good writer, question mark.

06:10 - Brent Simoneaux 

Yeah, I think so.

06:12 - Johan Philippine 

Oh, thanks, Brent. But I don't think I could contribute anything technical to the Fedora project, just based on my writing. My contributions would lie elsewhere. But writing is a skill. With time and with practice, writing documentation is something that most of us could do. I mean, it's not like we're expecting Shakespeare to tell us how to use this software.

06:35 - Angela Andrews 

And that sounds like a lot of work. I mean, if you're constantly trying to innovate, and then go back and try to document your steps, or document what information, it's probably not as much forward movement as said developer would like, because they have to go back and do the documentation, or bounce from task to task. That seems hard.

07:04 - Brent Simoneaux 

And if you're creating the thing, you might not have the best perspective to document the thing, right?

07:12 - Angela Andrews 

Yeah. Yeah. There are different viewpoints.

07:15 - Johan Philippine 

Exactly. I mean, Matthew Miller talks about this as well.

07:18 - Matthew Miller 

Sometimes when you're the person doing something, it's hard to know exactly what to document. You look at something and it seems obvious to you, and so you don't want to write down, "This thing does the obvious thing that it does." Whereas someone who's coming at it from the outside can look at it and maybe see what parts need more explaining, and what parts really are more obvious to an outsider.

07:42 - Johan Philippine 

If we put that all together, there's a constant need for documentation. There's an imbalance in the people with the required skill set. And frequently, there's a need for an outsider perspective. We end up with what we have today, which is a near constant need for people to write documentation.

08:02 - Brent Simoneaux 

I mean, what do you think is going on there? Do you think it's a time issue? Do you think it's a perspective issue? Do you think it is a skills issue? Why is there such a need?

08:17 - Johan Philippine 

I think it's a little bit of all three. It seems like if we want to have more people writing documentation, and doing all these other ancillary tasks that these projects need to have done, we might want to try and broaden the community beyond the people that we're reaching right now, which seems to be mostly a developer audience.

08:39 - Angela Andrews 

How do you propose we do something like that?

08:42 - Johan Philippine 

That's a very good question. I don't have the answer for that, but part of it might be doing more to highlight the benefits for the writer, in terms of what they can gain from writing technical documentation.

08:58 - Angela Andrews 

All right.

09:04 - Johan Philippine 

All right. Other people need you. But what's in it for you, as a writer? There's that satisfaction of helping others, but-

09:14 - Brent Simoneaux 

Altruism has its limits, right?

09:15 - Johan Philippine 


09:16 - Angela Andrews 


09:17 - Johan Philippine 

Yeah. I mean, like we said, it's difficult work and it takes a lot of time. You might be able to convince some people to write for documentation a little bit, but these are projects that need enduring participation.

09:33 - Johan Philippine 

So let's talk about what the writers can gain from drafting technical documentation. We spoke to Ben Cotton. He's a Fedora program manager here at Red Hat, and that's a fairly technical position. But when he first got started in open source, he may not have thought that he would get there.

09:52 - Ben Cotton 

So when I first got started, I could probably code my way out of a paper bag, but not much further than that.

09:59 - Angela Andrews 

Wait, so you're telling me that he started writing documentation for Fedora, and he's now on the product team?

10:08 - Johan Philippine 

That's right.

10:08 - Angela Andrews 


10:09 - Brent Simoneaux 


10:09 - Angela Andrews 

That's impressive.

10:12 - Ben Cotton 

Because most projects need more documentation, being willing to step up and contribute there makes you very popular with the core contributors. And it's a great chance to show that you're willing and able to make quality contributions. And it provides a learning experience, because as you fill in the gaps in the documentation, you'll naturally just have to learn more about the software.

10:33 - Johan Philippine 

He just packed a lot of information in there. He's doing this technical stuff now, but he started with documentation. And by learning the documentation and writing the documentation, you get to really learn the ins and outs of the software.

10:47 - Angela Andrews 

That is awesome. I'm just saying, this sounds like the recipe that so many people are looking for, to try to find their way and become more technical. I don't think this is the avenue a lot of people think about, but Ben clearly was able to turn his contributions into a very technical and very important position here at Red Hat.

11:15 - Johan Philippine 

It's also a really good way to get noticed and in the good graces of the project's maintainers, but you've got to be sure to pace yourself accordingly.

11:25 - Ben Cotton 

Yeah, so when I first started in the Fedora documentation team, I was a little optimistic and volunteered to update the RPM guide, which was basically book-length content. It hadn't been updated in a while. So I was like, "Hey, I'll take that on. Look at me, the new guy trying to help out." And it turned out to be a much bigger project than I could realistically take. Once you got past the first few chapters, the technical depth got way beyond what I knew at the time.

11:55 - Johan Philippine 

Now, luckily, he didn't give up on contributing at that point. And he comes back to what we were just talking about, about how it's a great way to improve your tech skills.

12:05 - Ben Cotton

Working on documentation definitely helped my tech skills develop. For example, my first interactions with source control via Git came from the documentation work. I learned a lot about scripting and automating workflows with some of the documentation tool chains we were using at the time. Getting started in documentation, and then expanding into greater technical depth as time goes on, is a fairly common use case.

12:35 - Johan Philippine

If your goal is to transition to more technical contributions in the long run, there's another thing docs can do for you.

12:45 - Angela Andrews 

Write this down.

12:51 - Ben Cotton

There’ve been a lot of times, trying to write documentation for something, where I've discovered a bug in the code, because the documentation said, "We should do this." I'm like, "Okay, checking, checking, checking. Oh, it doesn't do that."

13:05 - Brent Simoneaux

Let me see if I understand what Ben is saying here. If you are interested in contributing to an open source community, but maybe don't know how to do that, that documentation is maybe a good way to get started.

13:22 - Johan Philippine 

Yes. It gives you practice on how to contribute the code. With Git and source control, that's not a trivial skill to learn. And on top of that, you learn how the project works itself. So you're looking at someone else's code and figuring out, "Oh, okay, here's how this code put together ends up doing this task." And so you're seeing examples of code at work. And that's something that you can then build upon and learn for your own education.

13:55 - Brent Simoneaux 

Is there also something here, and maybe I'm reading between the lines a little bit, that you're just kind of helping people out, and that's a way of meeting people in that community.

14:09 - Johan Philippine 

Yes. He talks about becoming very popular with the core contributors. These are the developers who make routine and very regular contributions to the project. And oftentimes, that's what their main job is. They're writing the code, and they may not have time to do a good job on writing the documentation. So if you volunteer to help them out with that, they're going to be thankful that you've helped them out.

14:40 - Johan Philippine 

So we've been talking to Ben Cotton about people who might want to be more technical contributors, and how documentation helps them learn the software, helps them become more technical. But that's not necessarily the career path for everyone. Even earlier than that, we were speaking about trying to get a more diverse skillset in the open source community, so it's not just developers. We spoke with Nicole Baratta, and that's exactly what she did. She is technical writer, and she made writing documentation a career.

15:15 - Nicole Baratta 

So what led me to working in documentation primarily was my first job outside of the library. So I started to work for a library open source software support company. And our primary software that we supported was Koha. And my boss looked at me during one of our training sessions and he said, "Hey, you're good at this training thing. And you're a writer, aren't you? You should write the manual for Koha." And that was it.

15:52 - Johan Philippine

Now, we just heard from Ben about biting off more than you can chew. And it sounds like writing the entire manual for an open source project seems like a really big thing to handle.

16:06 - Angela Andrews

A bit much.

16:07 - Brent Simoneaux 

She's a writer. Is that right?

16:09 - Johan Philippine 

Yeah, so she has a really interesting background. She has a background in library sciences, but also in computer science.

16:17 - Brent Simoneaux 


16:18 - Angela Andrews

Very interesting.

16:20 - Nicole Baratta 

We didn't have any documentation for Koha before that. So I sat down and I took my materials for training on how to use the software, and I started from scratch. Was just clicking away, how to install, how to set up, how to use it every day. And that was the beginning of my technical writing background, and the beginning of the manual for Koha.

16:47 - Brent Simoneaux 


16:48 - Johan Philippine 

Yeah. Because she had all this material to pull from, it made it a lot easier to tackle such a big project. But she did all the work ahead of time, in order to be able to do something that large.

17:00 - Brent Simoneaux 

Yeah. Well, it's interesting, because I think what you're saying here, Johan, is that technical writing is a specialized skill. It's something you learn through doing. It's something you can study. It's something you can get better at. And it's a skill that can become a full-time job.

17:19 - Johan Philippine 

Absolutely. Nicole and many other people have made technical documentation and technical writing their entire career. And if you, in the audience, if you're considering writing documentation, Nicole's got a few pieces of advice for the kind of writing that she does every day.

17:39 - Nicole Baratta 

When you're looking at getting started, I would say, get started in the way in which you would want to read documentation. So don't jump into a project and start writing giant blocks of text. None of us read that on the web. We know we skim.

17:58 - Nicole Baratta 

Remember that the people that are going to be reading the documentation are going to be from all different levels of technical skill, or from various different fields. And so you need to take it from the very beginning, the very basics of how do you get this installed. And the last thing I would say would be, you have to remember that your documentation should be easy to translate.

18:29 - Johan Philippine 

That last point is pretty important. She goes on to talk about it for quite a bit, but I'm going to paraphrase a little bit. Essentially, even though a lot of people who are using and take part in the open source community are able to read and understand English, it's still a lot easier to learn something if you're able to do it in your native language.

18:51 - Brent Simoneaux 

I think at the foundation of this advice from Nicole is know your audience. Really understand your audience and write for them, whether it's geographically or culturally, where they're at, whether it's the context in which they're encountering your documentation. And then what they actually need, where they are in what they know, what is their knowledge level as well.

19:18 - Johan Philippine

And the knowledge level doesn't necessarily mean, if you're a beginner, it doesn't necessarily mean you need a large block of text to have everything explained. That can be intimidating in and a barrier in its own right. If you're trying to get into something and you see this huge wall of text, it's like, "Oh, this is going to be work."

19:36 - Brent Simoneaux 

Yeah. I got to climb this wall of text.

19:39 - Johan Philippine 

I got to climb this wall of text just to use this thing that I just want to download it and get it going. Brent, you said we should all be keeping the audience in mind, right?

19:50 - Brent Simoneaux 

Yeah. I mean, that is who documentation is for. That is why documentation exists.

19:57 - Johan Philippine 

And that's the last, but definitely not the least reason that we're doing this. The reason to write the documentation is for the user. It's about the community who are going to be using the project and who need to understand how to do so. We spoke with Robyn Bergeron, who reminds us to keep our focus on the audience.

20:18 - Robyn Bergeron 

Now, frequently, those things are written down in engineering speak, and don't really talk about why this is actually going to benefit or help an end user. It might have a couple lines about that. When I was doing that, it was almost being like the translator from engineering speak to human speak.

20:38 - Brent Simoneaux

Angela, I'm curious how you think about engineer speak.

20:42 - Angela Andrews 

Well, it's okay to speak it to other engineers. But to read it in documentation, especially with something that you're not familiar with and you're trying to become familiar with, it is not a great way to engage. It really isn't. It's almost like you're talking over someone's head.

21:02 - Angela Andrews 

I read a lot of documentation. And when I have to read that paragraph a third time, because it's a little bit too jargon-heavy and a little bit too wordy, no, that is not a good look.

21:16 - Brent Simoneaux 


21:17 - Angela Andrews 


21:19 - Johan Philippine 

Now, beyond that, we spoke earlier about keeping the docs up-to-date to make sure that it reflects the actual state of the project, but it's not just to make the project look good. If the docs are neglected, that has a real effect on users trying to learn how to use your software.

21:37 - Robyn Bergeron

All of that stuff is written down, but making sure that that's always clear and always very up-to-date, trying to make sure that it's not just some information that somebody wrote down once and then forgot about updating it, as things evolve or change, it turns out that if you don't update everything, then people get more confused, despite a process being easier.

22:03 - Robyn Bergeron

So for me, that's always been one of the things I'm most passionate about is just getting rid of roadblocks for users. And if you don't have things properly documented and documented in an up-to-date fashion, then you're losing a captive moment with somebody who actively is really thinking, if they're hovering over some documentation in that moment, they're really thinking about it. And if you lose that, because you don't actually have the proper information present, then maybe they'll be persistent, maybe they'll give up and move on to something else.

22:33 - Brent Simoneaux 

I imagine it's really difficult to keep documentation up-to-date.

22:37 - Angela Andrews 

It is. Technology moves so fast. How can you keep up?

22:44 - Johan Philippine 

And this is something I've personally run into, where I was trying to get something up and running on my own amateur home server. And I was reading through the docs and I noticed that the version of the software I was running was more recent than what the numbers were in the documentation, and something wasn't working. That's not a great feeling for me, because that really points out my own inadequacies, in terms of being able to get something running.

23:14 - Brent Simoneaux 

Has that ever happened to you, Angela?

23:16 - Angela Andrews 

What? It happens to me all the time. It happened to me two days ago.

23:20 - Brent Simoneaux 

Two days ago?

23:21 - Angela Andrews 

It's always happening. Okay. Long story short, I'm installing a hypervisor on a laptop. It's a pretty beefy laptop. It's not very old. This particular hypervisor had ripped out these drivers, and I didn't know it. So I'm trying to install said hypervisor and figure out, "Well, how do I embed the drivers into said installer?" Never done this before. The documentation that I ran into didn't mention that. No, it happens all the time.

23:54 - Brent Simoneaux 

I think one of the things that I'm taking away from this is empathizing with other people, and I think that goes two directions. So one, you have to empathize with the people who created whatever you're documenting, the engineers with the engineering speak. You have to speak their language and really understand what is happening. At the same time, you have to understand your end user, and really know what they need from the documentation. So you have to have a lot of empathy, in order to be successful in a job like this.

24:40 - Johan Philippine 

I think empathy is a big part of doing it right.

24:44 - Brent Simoneaux 

Yeah. It's almost like the technical writer sits between the engineer and the end user. And if that link in the chain gets broken, or something breaks down at that step, the user is just left with frustration, trying to install their drivers, like Angela.

25:08 - Johan Philippine 

Right. It didn't get done, and someone could step in and make it better, and make it better experience for everyone.

25:15 - Brent Simoneaux 


25:15 - Angela Andrews 

You don't mean me, do you?

25:20 - Brent Simoneaux 

Well, here's a question for you, Angela.

25:22 - Angela Andrews 


25:22 - Brent Simoneaux 

Have you ever contributed to an open source project?

25:27 - Angela Andrews 

No. Well, for a product that I'm actually using, or would like to use and learn, I've never done it. And after hearing all of the interviews today and hearing their outlook on it, it is really something that I'm interested in doing, because it seems like such an amazing way to learn a product. I think it's something that I might have to do, because I see the need. It's been explained to me very clearly that this need is out there, and I like to write anyway.

26:06 - Johan Philippine 

I think if you're looking for a way to start contributing to open source, writing some documentation will be beneficial for everyone. And likely, you'll be welcomed with open arms.

26:18 - Angela Andrews 

I can see that in my future. And I have one in mind too.

26:22 - Brent Simoneaux 

Oh, okay.

26:23 - Angela Andrews 

Because it's a product that I've never used before, and I really want to get intimate knowledge of it. So I have one in mind. Yes.

26:32 - Johan Philippine 

And Brent, there's no reason you and I also shouldn't be able to contribute to open source.

26:38 - Angela Andrews

You can help me out.

26:40 - Johan Philippine 

We could.

26:40 - Brent Simoneaux 

We are writers, after all.

26:41 - Angela Andrews 

You are writers.

26:45 - Johan Philippine 

We got to even that balance a little bit.

26:47 - Brent Simoneaux 

That's true. Some projects actually make this somewhat easy. So one example, and I want to introduce both of you to this, there's a website called What Can I Do for Fedora? So if you remember earlier, we talked about the Fedora project, and they actually make it quite easy to figure out how to get involved and what you can do to help.

27:10 - Angela Andrews 

Oh, this is cool.

27:12 - Johan Philippine 

And we can include that in the show notes.

27:14 - Angela Andrews

Oh, yeah. Definitely. I like this idea. You know what? This is one of those ideas that if someone asked me, I'm definitely going to suggest it.

27:26 - Brent Simoneaux 

So if we are going to write some documentation, or if someone who's listening to this right now is going to write some documentation, I think we're going to need some good models, some good examples of documentation at its best.

27:44 - Angela Andrews 

Okay, audience, you have to help us out here. What have you found helpful in terms of documentation? Share with us some examples of some helpful, some really well-written, some exceptional documentation that you've come across. We definitely want to see it.

28:01 - Brent Simoneaux 

We want to see it.

28:02 - Angela Andrews 

So you can hit us up @redhat, either on Twitter or Instagram. And don't forget to use the #compilerpodcast.

28:11 - Brent Simoneaux 

And tag the person who wrote it.

28:14 - Angela Andrews

Yes, yes.

28:14 - Brent Simoneaux

Tag the documentation writers, so we can all give them thanks.

28:20 - Angela Andrews 

And that does it for this episode of Compiler.

28:24 - Brent Simoneaux 

Today's episode was produced by Johan Philippine and Caroline Creaghead. Victoria Lawton insists we document all the things.

28:34 - Angela Andrews 

Crossing t's and dotting i's. Yes. Our audio engineer is Kristie Chan, with some help on this episode from Olivia Kwan. Special thanks to Shawn Cole. Our theme song was composed by Mary Ancheta.

28:50 - Brent Simoneaux 

Special thank you to our guests, Matthew Miller, Ben Cotton, Nicole Baratta, and Robyn Bergeron.

28:57 - Angela Andrews 

Our audio team includes Leigh Day, Laura Barnes, Claire Allison, Nick Burns, Aaron Williamson, Karen King, Boo Boo Howse, Rachel Ertel, Mike Compton, Ocean Matthews, and Laura Walters.

29:12 - Brent Simoneaux 

If you want to help the show out, please rate it, leave a review, or even better, share it with someone you know. It really does help us out.

29:22 - Angela Andrews 

And you share it with two people, and they share it with two people, and they'll share it with two people. But thanks again, everybody. We'll see you soon.

29:31 - Brent Simoneaux

No one gets that reference. All right. Bye, everybody.

Compiler background

Featured guests

Matthew Miller

Ben Cotton

Nicole Baratta

Robyn Bergeron

We were so excited about our episode on licenses—so we have a special project that we want to share. Our Compiler theme song is now under a Creative Commons license. Add your own special touch to our theme. Remixes have the chance to be featured on a future episode.