The OCTOpod: Conversations with SUSE's Office of the CTO

Documentation and Open Source with Anne Gentle

August 26, 2021 Alan Clark - Office of the CTO, SUSE Episode 6
The OCTOpod: Conversations with SUSE's Office of the CTO
Documentation and Open Source with Anne Gentle
Show Notes Transcript

There is a perception in the tech world that developer documentation is boring, and it can be a major challenge to get people to contribute to open source docs. Luckily, today’s guest, lifelong learner Anne Gentle, is always up for a challenge. Anne’s open source journey began by volunteering for organizations such as One Laptop per Child, and getting involved with book sprints. This was a way for her to learn about innovative techniques being used in open source which she was missing in her job as an everyday technical writer. The value she gained from entering the world of open source documentation, and the value she could see it provided to organizations, inspired Anne to write a book; Docs Like Code. In today’s episode, Anne shares some of the principles she covers in her book, explains the parallels that exist between documentation and software development, dives into some industry changes which have transformed documentation over the past few years, and offers valuable advice for anyone interested in getting involved in open source.

Key Points From This Episode:

  • Anne explains where open source and documentation intersect.
  • Why Anne chose to get involved with open source volunteering.
  • A variety of other reasons that lead people into the world of open source volunteering.
  • Growth in the number of open source writers over the years.
  • Using GitHub as an example, Anne explains the value of open source to organizations. 
  • Why DOCSIS code techniques pair well with open source.
  • The motivation behind Anne’s book, Docs Like Code. 
  • Industry changes which influenced the documentation changes. 
  • Parallels between software development and documentation.
  • Advice from Anne regarding putting systems in place for writers.
  • How the CICD has been helpful for documentation.
  • The factor that is vital to successful documentation.
  • What Anne wished she knew more of before entering the open source world.
  • Anne’s biggest surprise when she started working in open source.
  • How the open source ethos is applicable to Anne’s current role. 
  • Valuable advice from Anne for anyone interested in open source.
  • Google's Season of Docs program, and the impacts that Anne expects it to have.

Links Mentioned in Today’s Episode:

Anne Gentle on LinkedIn

Anne Gentle on Twitter

Anne Gentle on GitHub

Docs Like Code Website

Cisco DevNet

Write the Docs

A guide to getting started in open source

Season of Docs program

Just Write Click

Outreachy Internships

One Laptop per Child

[00:00:02] ANNOUNCER: Welcome to the OCTOpod, hosted by Alan Clark, and brought to you by the SUSE & Rancher Community. Alan has spent his software career focused on open source advocacy and emerging tech. In the OCTOpod season one, Alan talks with experts across technology about trends and challenges in open source, from building communities to diversity and inclusion, to keeping the open in open source.

[00:00:36] AC: Hi, everyone. Welcome to the OCTOpod. We're continuing our conversations about open source. Today I'm joined with Anne Gentle. Anne’s books promote collaboration amongst developers, writers and other stakeholders within open source and enterprise communities. Currently, she is in charge of developer content, the API documentation and the developer experience on the Developer Relations Team at Cisco DevNet. Anne supports open source tools for API design, documentation and developer support. Anne, it's great to have you here today. Thank you for joining me.


[00:01:15] AG: Oh, thanks so much for inviting me, Alan. This is going to be a fun conversation.


[00:01:20] AC: I think so. I have to tell you, I've been looking forward to chatting with you on the topic of documentation, because quite frankly, getting documentation done in an open source community can be very challenging, I've found over the years. Having worked with you in open source over the years, I've been very impressed in how you're able to rally community members to deliver cut documentation. I know that's not easy working with engineers, right?


So, I really want to talk about how we rally those community members, and how you deliver the documentation for those who want to use the open source project, and also, for those that are working on the project. I know there's many out there who write code, but have no interest in putting words on paper. I'll never forget the first time I had a developer talk to me, and I was pushing on to document what he had written. He says, “Hey, for me, the code is the documentation.”


[00:02:18] AG: You hear that a lot.


[00:02:19] AC: We hear that a lot, don't we?


[00:02:21] AG: Right.


[00:02:23] AC: Where does documentation and open source intersect?


[00:02:28] AG: There's definitely a lot of intersection. I think over the years, especially with a DOCSIS code world, we can see more easily what open source documentation can look like. Where you have open source code, you can also have open source docs, where you can see the source of the documentation, and contributors can view it and edit it. Especially in software and APIs, the docs can contain code examples. You probably want to open license those for reuse, for someone to repurpose, use them in their own code.


Open source documentation is very similar. You want reuse, you want re-adaptation, you want people to get in there and take a look and make it better. At a basic layer, open source documentation should have a way to see the source and a way to contribute to the documentation for sure.


[00:03:22] AC: It sounds like it works just like code. You're checking in, checking out, reading, contributing. Very much similar model. What are some of your experiences in working on open source documentation? More specifically, what's the rallying point that you found that gets people to want to help create that documentation? What motivates them?


[00:03:44] AG: For me, working in open source was a way to experiment, so I could actually open new doors, and I found a new career path. I was working as an everyday tech writer, and I wanted more innovative techniques. I couldn't really try those in my day job. Volunteering in a community was a way for me to try things out. Every time I wanted to learn something new, I could find a way to play around with it by volunteering. Open source is exactly the way to go about that volunteer aspect.


Honestly, in a way it's a selfish motivation. I was looking around for ways to use Wikis for technical documentation. I didn't have a reason to do it at work. I found out that there were open source projects doing it. For me, I volunteered with One Laptop per Child. I learned about book sprints, which was a way to gather together the people that knew the most about the project, and write a book in a week. I wrote a book about those techniques. Open documentation, using Wikis for documentation, how to write collaboratively.


Here's the thing, I kind of wrote a job description by writing that book and that led to the OpenStack job. That has been my experience. It's been a very career path. It was a way for me to practice, volunteer, get better at it, and find ways to coordinate as a job. I was very privileged to be able to do that. One thing led to another.


[00:05:18] AC: Yeah. I was going to say, it sounds to me like, it opened up some doors for your career as well.


[00:05:22] AG: Oh, certainly. Yeah.


[00:05:23] AC: Definitely changed the direction.


[00:05:25] AG: Oh, and I think, people have all kinds of motivations for helping out. For me, it was a chance to learn. People also like to feel part of a group, part of a bigger movement, part of a purpose. There's great reason to connect with others. Maybe you're trying to figure something out, and you want to find somebody else in a similar situation, right? That's a great motivator. I think, you can also find people doing things that you're just trying to learn about, or build more relationships across more diverse bridges that you may or may not be able to find in your job.


I think, especially with technical writing and writers, we love to practice our craft. We love to hone our craft. Really good tech writers are this precious commodity. It's also a feeling of like, “Can I be helpful? Can I write for my future self?” Developers know that three months from now they're going to look at that code and be like, “What was I thinking?”


Even code comments and learning how to write those well are just things that people want to get better at. I think, part of it is, you might think some of it is altruistic, especially when it's very purpose-driven, but there can be selfish reasons. You can be driven in a learning education, getting better at something is a huge motivator.


[00:06:49] AC: In your experience, who are the roles of people that have been contributing to open source documentation? Is it the developers themselves? Is it the users?


[00:07:04] AG: I actually went and looked up stats from one of the first releases for OpenStack. We had three docs contributors, and over 500 developers that had done contributions. It was out of whack. That ratio was really small, as far as writer contributors. Over the years, we were able to get more and more developers who could write, and especially for API docs, that bridges this gap between writers who are actually using it, and they could do small changes that would help someone out in the future, especially for writing code examples in docs. I think, developers are very conscious of how they can help others, even with just small changes.


The closer you move the docs to the code, especially with the DOCSIS code techniques that I think are becoming more and more popular, developers are catching on like, “Oh, this makes total sense. Release the docs with the code. Put it as close as you can for reviews and everything else.” It's just becoming more and more logical. There's a community called Write the Docs. It's got a lot of developers in it, who want to get better and better at writing, and figuring out the best tooling for documentation. There's a lot of different roles in open source, in the community of people who are interested in documentation and all kinds of documentation, for sure.


[00:08:27] AC: Okay. We talked about the individuals a little bit, but what about the organizations themselves? Why should an organization open source their documentations? I guess, quite frankly, are they heading that direction? Is that where we're going?


[00:08:43] AG: There are some really great recent examples. GitHub actually wrote a blog post about how they recently open sourced their docs. I got to talk to their Hubs manager at the time, and she said, “You know, what happened? Someone had written a really good PowerShell, GitHub actions guide, and was like, “I really want to publish this somewhere.”” They looked at it, and they're like, “This is great.”


What they found is that they can work really well with people if they've worked in the public. It made natural sense for GitHub to write on GitHub. If you read their posts, open source gave them that long-tail of experts, the people who knew every nook and cranny of some specialized use case of their features. They were writing excellent tutorials already. The thing was, it was faster than their tech writers could get in there and learn it at an expert level. Their reasoning was, “Opening it up is the best way to work. The best way to be writing is to write in the open, in public, using the tool chain that we work on every day.” Made total sense.


[00:09:48] AC: Made total sense. They've got cleaner docs, got accomplished faster, got all the experts to contribute, give their feedback. Makes total sense.


[00:09:59] AG: Oh, yeah. I want to say, Microsoft and AWS were recent ones in probably the last two years. They're using DOCSIS code. They're giving everybody the ability to send in pull requests. That's where you send in a change that you want to make to the documentation. On GitHub, it's called pull request. On GitLab, it's called something else. It's basically, a way to say, “I'd like to give you guys this change. Can you incorporate it?” I think these DOCSIS code techniques pair really well with open source.


[00:10:30] AC: Okay, cool. You mentioned docs and codes. You've mentioned your book that you've written. Why don't you give us a little bit of overview about what it's about?


[00:10:40] AG: It really was a way for me to kind of go, “Okay, I'm doing all these techniques. I really don't want to work in another way. This is continuous integration, continuous deployment for documentation.” I had these build systems that were automated. I was working with developers. It really is treating docs like code. We had tooling in OpenStack that was wonderful, amazing, really innovative. It let us combine the power of the developer tools and techniques. It also let us also get really excellent technical documentation written. It's this combination. It's the art and craft of writing, along with the art and craft of software development. You hear the term DevOps, well, this is doc ops, right?


[00:11:29] AC: Doc ops. Yeah.


[00:11:30] AG: I love it. It's just a really great way to work. I think there's more and more communities gathering around it too. I was looking around like, “Well, who else is doing this? We should write this down.” I was like, “Well, I guess I better write it down.” That's how the book came about.


[00:11:46] AC: Okay. That sounds like a radical change in the documentation world. Is it? Is it a radical change? Or is it just my perception?


[00:11:54] AG: I think, it is changing and shifting along with the industry shifts we're seeing. We're more mobile as a workforce. Pre-COVID days even, we were doing a lot more working at home. We were working a lot more with a global workplace. We were mobile. I can't remember the last time I was handed a desktop computer as opposed to a laptop. There's more and more APIs to document, both internally and externally.


You can see this complete addition, especially in the REST API world of web APIs, the industry itself has basically made it so the documentation had to move along with it. Agile techniques for software development meant that the documentation had to become more agile as well. Work in sprint. Work very similar to the way the developers work. I really think it's not the way – documentation changed because the rest of the world changed as well, for sure.


[00:12:56] AC: We've been talking about a lot of different principles here. I want to talk about the principles that are in your book, the book Docs Like Code, right? That's the name of the book. Let's step back a little bit, and maybe get a little basic again. How do those principles align with open source documentation?


[00:13:14] AG: Yeah, so there's a definite source for the docs and output for the docs. With Docs Like Code, you have to figure out the tooling to get that to happen. There is alignment. There's alignment with tools. There's alignment with techniques. I mentioned agile. That's a developer software process that people can adapt for documentation. There's lots of, basically, tools.


If you think about versioning, of course, you version software. Well, your documentation needs to be versioned as well, so when your end-user walks up to it, they know what version they're using. Docs Like Code is really just a way to look at each part of the documentation process. You work on it, you find bugs. Well, let's track those bugs in a bug tracker, right? You publish, which is the same as releasing in software vernacular.


This book really gives us a chance to show there's a shift in shared code tools. There's a way to version your docs with the code. All of those principles are really what lined up really well, especially with API documentation, especially with software documentation, and open source is where all of that is heading.


[00:14:35] AC: Those principles sound very, very similar to those with open source code. It seems like they are aligned very well. Are the basic structures the same? Are we very much talking about the same thing? If I'm used to writing code, I'm going to find writing documentation exactly the same? Is there something that's different?


[00:14:55] AG: There's a lot of parallels. One of the first questions people face when they're working on DOCSIS code is, “Well, do I put my docs directly in the same repository as the code?” For example. Or, “Do I put the docs in a separate repository? At what point do you have multiple docs repositories?” There's a lot of analysis that goes into, “What's my audience? What are they going to want to do with the documentation? What outputs am I going to have?”


If you're just talking about writing concepts, say, that might work well in a repo that just stands alone, and you have separate reviewers for it. Reference documentation, that might need to live right next to the code. There's basic structures you'll put in place, just based on repositories, which are, what are the storage units for the source? I mentioned versioning a little bit. Versioning is a whole land on its own.


Yeah. I think there are certain parallels and structures you can put in place. Here's the thing, I firmly believe that whatever contribution system you have in place for developers, make it the same for the writing. Make very similar systems. Track your issues in the same way. Do your releases in the same way. Keep your versioning very similar. You're going to have very good adoption, because people won't – there won't be barriers. A developer won't say, “Well, I don't know how to do that.” A writer won't necessarily think, “Well, that's not for me,” because they'll see the patterns of publishing that are well recognized.


[00:16:35] AC: Okay. You named things like contribution and structure and getting those aligned with the code. Do you think those are key? I'm thinking of communities that are struggling in getting their open source documentation off the ground. Are these the key factors in getting documentation rolling forward, getting people to contribute and consider helping?


[00:16:56] AG: One example of a really great radical update for docs was the use of CICD. That's that automation pipeline, where you're building everything automatically based on a trigger. And read the docs tooling. That was one of the first examples, where it was super easy for people to put something into a build pipeline that resulted in documentation that was published to the web. I think, if you have CICD in place, and then you can figure out how to put your docs into that system, that's going to be a huge leg up for your documentation.


If you already have a bug system, and all you need to do then is this little lift, where you would say, “Okay, in the bug system, I'm going to start tagging things as docs.” It's basically a way to use the systems that are in place already, and just maybe have a little flag that just indicates, let's use this for docs, let's use that for docs. Now, tools are tools, systems are systems, and it's still about the people. Beyond your systems, you really want to have a culture of people who value documentation highly, who really have that sense of wanting to help others, wanting to help their future self. I still think that's a great [inaudible 0:18:11].


I think the Python community is a really good example of that culture. I guess, I think of this, because the Write the Docs Community, which is, again, that community of both developers and writers basically working together, building bridges, figuring out how each other work. I think I tie them together, because the founders of Write the Docs were in the Python Software Foundation, and just have that ethos of a culture of great docs are going to make for better software, better APIs.


[00:18:40] AC: Totally agree. Okay, so let's step back. Let's go back to day zero. When you first got started in this whole realm of open source and open documentation, what do you wish that you knew then, that you know now? Then from there, what surprised you most about working with open source documentation?


[00:19:04] AG: If I'm perfectly honest about what I wish I knew, I wish I knew more basic Unix system administration, and I'm not even kidding. Or even just basic networking understanding. I work at Cisco DevNet. We have a certification program now, that's DevNet Associate. It has a great blend of needing to know networking basics and programming basics. Even just studying for that certification just brought me to realize like, “Man, it would have been so much easier if I knew these fundamentals to begin with.” I'm a lifelong learner by habit.


[00:19:39] AC: I was going to say, we're always learning though, right? That's the beauty of it.


[00:19:43] AG: Yeah. I think, just Unix and networking would’ve helped me grasp cloud computing so much more quickly. Command line and automation is just so efficient. It's my favorite thing, I think. Anyway, that's what I wish I knew as technical things, I think.


[00:19:59] AC: Sure. Sure. Any big surprises? Any, “Aah.” The cries.


[00:20:05] AG: The best surprise was how grateful people were for any documentation at all. Even if I was like, “This is terrible. This is awful. I can't believe I'm even writing this,” people would seek me out at events and be like, “Can I find Anne Gentle? Thank you for what you've done so far.” People were so grateful. It's just rewarding. That keeps you going. Even just that little bit of gratitude could keep you going for the next release, where it's like, “I have a pile of work. I'm facing this mountain of messiness, but I can keep revising, and keep getting more people gathered around who find this stuff interesting as well.” That surprised me the most, that people were happy with stuff that I was like, “Well, it’s better than what we had before.” Yeah.


[00:20:55] AC: Which was nothing.


[00:20:57] AG: Yeah. It was a nice surprise, that people were super, super grateful.


[00:21:02] AC: You mentioned your role there at Cisco with DevNet. Can you tell us how the open source ethos apply to your current role?


[00:21:10] AG: Yeah, absolutely. At Cisco DevNet, my current role is working with a small inner team to support almost 2,000 contributors to the API docs on We're using a DOCSIS code system. We are encouraging people who write in the open, basically amongst Cisco people, and that way, we get better technical accuracy, right? We're enabling the technical writers. We're enabling the engineers. Cisco has a sales engineer role. Cisco has a technical marketing engineer role.


We're making sure that more and more people can write the docs, the developer docs for Cisco DevNet. I think, by reaching out to people that are closest to the docs, we're able to breathe life into what some people think are boring, “Developer docs, that must be boring.” It's like, well, no. It's not so static. It's not so dull, if you get more and more contributors, if you get more and more people close to the product, who knows the original reason why that feature was made.


That's the key for us at Cisco DevNet is just, Cisco's a big place, so the more outreach we can do to get better and better documentation in this DOCSIS code system, I think that's how we're able to get that open source ethos spread. Teams are now seeking us out with our tool, because they want to use it to write new docs. They love using GitHub to collaborate on their documentation.


It's just a sense of, okay, this is the open source way is to do this outreach, to try to make sure that people can use tools that are shared, that we all work on together. I mean, because part of my role also, that's really exciting, is we're working to improve our DOCSIS code tooling, so we can bring in requirements from teams if they need something. We're doing new interactive API docs. It's just a really great way. I love working on open tools as well. They're not proprietary and locked away. My sense is that we can have this open source ethos and the collaboration in the tool chain, and in the outreach, and that just, like I say, it breathes life into something that people might think is boring.


[00:23:35] AC: It doesn't sound boring, the way you've stated this. I mean, you described how you're getting contributions from across the community. I'll call it the community, right, from the systems engineers, and sales force, and so forth. Really, you formed an inner community there from across – okay, I'm going to use the word community. From across the community. It sounds like the contributions are really varied both in content, and, you know, from bug fixing, and suggestions to actual contributions, like code snippets and so forth. Maybe one final question here. If you had to describe in one sentence, how do you get people to be involved in open source documentation?


[00:24:20] AG: Yeah. I don't think there's one sentence, because probably, there's several approaches. There's a really great talk on the Write the Docs site. It's by Abigail McCarthy. Hopefully, we can put it in show notes. Basically, about how to get started with open source documentation. I love what she had to say. One of the things is like, “Well read the docs that are existing out there.” Even just realizing that open source documentation is a place to start and a good place for anyone to take a look, I think that is actually a really good starting point. I don't know. I'm not sure if I'm totally answering your question. I'm certainly not answering it in one sentence.


[00:24:59] AC: That’s good. That’s fine.


[00:25:02] AG: In the technical writing world, it has become more interesting to professional technical writers to work on open source and to figure out how to work in the open and have opportunity to learn the DOCSIS code tooling. If you want to get started in open source, and you're not sure where to start, I think documentation is a good place to start. I think, picking some goals, why do you want to get started? That lets you be more targeted in what you're going to try. Maybe your goal is to figure out how to work on bugs. That might be different than your goal being, “How do I work on tooling?” Right?


I think that, especially for documentation, you only have fresh eyes for a little while. Early contributors are really valuable to open source projects as well. Reading those docs for the first time, could be really valuable to a project, and giving that input. Yeah.


[00:25:58] AC: My injection here would be that, if I'm new to a project, what a great place to learn the project itself and how it works, right?


[00:26:05] AG: Exactly, exactly.


[00:26:08] AC: Perhaps, maybe a totally different question, as we go along here. Are there any other, any cool projects that you'd like to highlight?


[00:26:16] AG: Oh, in the world of open source and documentation, I really love what Google is doing with this Season of Docs program. It's basically an opportunity for people to learn about open source, and basically, give support for the open source projects to get paired up with professional technical writers. The technical writers want to learn more about how to get experience in open source. The projects, probably, have documentation that they wanted to improve, but haven't necessarily found a way to do that. I just love it.


It's along the vein of the Outreachy program that pairs mentors and students. It's in that wonderful world of let's match people up who have specific goals, and with the outcome of better documentation. I've just been amazed.


I serve on the board at our local Austin Community College. I've actually been studying this Season of Docs program from a tooling standpoint, even to show how open source tools are an important thing that maybe students should be learning in community college. Season of Docs is a wonderful program. I think it's going to have effects across multiple places in the technical writing community, in the open source community. I really love what they're doing.


[00:27:39] AC: The world of documentation is definitely transforming, isn't it?


[00:27:42] AG: It is.


[00:27:44] AC: Well, Anne. Thank you. It's been terrific to sit down with you today and talk about this. Thanks for sharing your experiences. Thanks for sharing your wisdom with us. For all you, listeners, thank you for tuning in and we'll see you again soon.




[00:27:58] ANNOUNCER: Thank you for tuning into this episode of The OCTOpod. Subscribe to the show wherever you listen to podcasts, so you'll never miss an episode. While you're at it. If you found value in the show, we'd appreciate a rating on iTunes. Or if you simply tell a friend about the show, that’d help us out too. You can connect with us at SUSE & Rancher Community at