Why Should You Write Technical Documentation?

  |  Compiler Team  
Cultura e processo
Sviluppo professionale

Compiler • • Why Should You Write Technical Documentation? | Compiler

Why Should You Write Technical Documentation? | Compiler

About the episode

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.

Compiler team Red Hat original show

Iscriviti

Subscribe here:

Listen on Apple Podcasts Listen on Spotify Subscribe via RSS Feed

Trascrizione

Brent, Angela, today, I want to talk to you about your experiences trying out open source software. Brent, would you like to go first? Because my experience is probably going to be wildly different. 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. What did you end up doing? Honestly, I got frustrated and just left. I shut my computer down and I just stopped. 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? 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. 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. Where does documentation come from though? It seems like a pretty specialized skill to me. Who writes documentation? Well, Brent, that's today's question. Why should you write technical documentation? Me? Mm-hmm (affirmative). Yeah, you. You too, Angela. Oh, yeah. Me. Yeah. You're not getting out of this. This is Compiler. An original podcast from Red Hat. We're your hosts. I'm Brent Simoneaux. And I'm Angela Andrews. We're here to break down questions from the tech industry, big, small, and sometimes strange. Each episode, we go out in search of answers from Red Hatters and people they're connected to. Today's question, why should you write technical documentation? Producer Johan Philippine is here to help us out. 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. I also feel like it's an opportunity that doesn't get a lot of attention either. Yeah. It's not the sexy way to get involved, if that's such a thing. 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. Documentation is always vital. There's a constant need to keep up with things, and there's always new things to explain. I think that starts to get at why this is such a persistent problem. I mean, it's often a Sisyphean task. We're pushing boulders up a hill. 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. 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? That's a huge one, yeah. And I believe they have two updates a year. Yeah. Is that right? That sounds about right, yeah. Yeah. That's a lot. 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. 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. On top of that, it's fairly rare to find people who are really good at two completely different skill sets. 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. Yeah. I see what he's saying there. Just because you're a good programmer, doesn't mean you're a good writer. Right. And I'm a writer. I'm going to go ahead and say that I'm a fairly good writer, question mark. Yeah, I think so. 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. 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. And if you're creating the thing, you might not have the best perspective to document the thing, right? Yeah. Yeah. There are different viewpoints. Exactly. I mean, Matthew Miller talks about this as well. 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. 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. 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? 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. How do you propose we do something like that? 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. All right. All right. Other people need you. But what's in it for you, as a writer? There's that satisfaction of helping others, but- Altruism has its limits, right? Exactly. Exactly. 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. 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. So when I first got started, I could probably code my way out of a paper bag, but not much further than that. Wait, so you're telling me that he started writing documentation for Fedora, and he's now on the product team? That's right. Wow. Really? That's impressive. 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. 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. 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. 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. 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. 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. 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. If your goal is to transition to more technical contributions in the long run, there's another thing docs can do for you. Write this down. 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." 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. 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. 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. 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. 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. 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. 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. A bit much. She's a writer. Is that right? Yeah, so she has a really interesting background. She has a background in library sciences, but also in computer science. Oh. Very interesting. 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. Wow. 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. 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. 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. 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. 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. 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. 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. 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." Yeah. I got to climb this wall of text. 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? Yeah. I mean, that is who documentation is for. That is why documentation exists. 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. 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. Angela, I'm curious how you think about engineer speak. 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. 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. Nope. Nope. 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. 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. 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. I imagine it's really difficult to keep documentation up-to-date. It is. Technology moves so fast. How can you keep up? 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. Has that ever happened to you, Angela? What? It happens to me all the time. It happened to me two days ago. Two days ago? 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. 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. I think empathy is a big part of doing it right. 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. Right. It didn't get done, and someone could step in and make it better, and make it better experience for everyone. Yeah. You don't mean me, do you? Well, here's a question for you, Angela. Yes? Have you ever contributed to an open source project? 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. 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. I can see that in my future. And I have one in mind too. Oh, okay. 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. And Brent, there's no reason you and I also shouldn't be able to contribute to open source. You can help me out. We could. We are writers, after all. You are writers. We got to even that balance a little bit. 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. Oh, this is cool. And we can include that in the show notes. 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. 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. 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. We want to see it. So you can hit us up @redhat, either on Twitter or Instagram. And don't forget to use the #compilerpodcast. And tag the person who wrote it. Yes, yes. Tag the documentation writers, so we can all give them thanks. And that does it for this episode of Compiler. Today's episode was produced by Johan Philippine and Caroline Creaghead. Victoria Lawton insists we document all the things. 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. Special thank you to our guests, Matthew Miller, Ben Cotton, Nicole Baratta, and Robyn Bergeron. 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. 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. 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. No one gets that reference. All right. Bye, everybody.

More about culture and process

A top-down organizational approach may miss out on ideas and innovation. Red Hat’s culture thrives on open core values, collaboration, and adaptability.

Articolo del blog

Single-instance Oracle Database on OpenShift Virtualization

31 luglio 2025  |  Mikhail Mikhailitchenko

...

Cloud automation

Articolo del blog

Friday Five — August 1, 2025 | Red Hat

1 agosto 2025  |  Red Hat Corporate Communications

...

Cloud automation

About the show

Compiler

Do you want to stay on top of tech, but find you’re short on time? Compiler presents perspectives, topics, and insights from the industry—free from jargon and judgment. We want to discover where technology is headed beyond the headlines, and create a place for new IT professionals to learn, grow, and thrive. If you are enjoying the show, let us know, and use #CompilerPodcast to share our episodes.