Abigail McCarthy (Staff Technical Open Source Communications Manager at VMware and Kelly’s former colleague from their time at Apprenda) joins Kelly and Kate in a conversation that leverages all the civil engineering metaphors: documentation as an avenue into open source projects; Abbie’s own pathway from OSS documentation lurker to active participant (her current titles also include Kubernetes SIG Docs Localization Subproject Lead); docs as an essential part of the bridge work needed to meet potential contributors (and even maintainers) where they are and get them comfortable engaging with such projects. Abbie also drops some best practices and recommendations, including the creation of a “culture of docs”.
This was a RedMonk video; VMware is a RedMonk client, but this video was not commissioned by any entity.
Resources
Kubernetes SIG (Special Interest Group) Docs
Abbie’s Write the Docs Portland 2021 conference talk, “A guide to getting started in open source”
VMware blog post on building better documentation practices for developers
Rather listen to this conversation as a podcast?
Transcript
Kelly Fitzpatrick: Hello. This is Kelly Fitzpatrick with RedMonk here with my excellent RedMonk colleague, Kate Holterhoff. We’re here with another episode of the Docs are In, and this time we’re going to be talking about open source documentation. With us today is Abigail McCarthy from VMware, who has a giant title that I’m not even going to try to pronounce. But Abbie, can you tell us a little bit about who you are and what you do?
Abigail McCarthy: Yes, hello. Thank you so much for having me on and really excited that we’re finally able to have this conversation. So I am a technical writer. I know Kelly mentioned my very long title, but basically what I try to do in my day to day job is to help open source communities build out docs communities and docs culture within their open source projects. So figuring out processes, trying to help get people involved, actually creating the docs on time for release. So going through all that process and really being an advocate for documentation within open source communities — that’s sort of me in a nutshell at the moment.
Kelly Fitzpatrick: That was a very succinct nutshell. I need to be able to talk about what I do in a nutshell that succinct and efficient. So to start off, I knew the story because you and I have worked before in previous jobs, but for folks who don’t already know you, how did you get into technical writing?
Abigail McCarthy: Yeah. So I always like to say that I kind of got into technical writing accidentally when I graduated with a computer science degree and I started working as a web developer. I did not know that technical writing was a field or anything at all. I had never heard of it until I was kind of looking for a new job. And a friend of a friend’s was like, “Hey, my company is looking for a technical writer, we do cloud computing, do you think you would be interested in that?” And after quickly Googling a little bit of what those words were, I figured out that technical writing as a field existed, and it was things that I was already interested in doing as part of the job that I was doing already. So coming up with documentation about processes of what things that we’ve been putting together, doing little trainings, thinking about how to organize information so that we can put things together for our clients and just internal things. So it kind of — through that was sort of my gateway into technical writing. And I ended up getting that job, which is where I met Kelly. So it was kind of an adventure in learning a lot of things. I had never done anything with the cloud before. I had not done anything with technical writing, so everything was just a lot of new information coming in and I’ve really never looked back. It’s been a really great experience being a technical writer.
Abigail McCarthy: It incorporates all of the things that I love doing, like coming up with processes, coming up with — investigating how things work and then conveying that information. It’s actually — it’s always funny to me that I do technical writing because I actually usually hate writing. It’s probably the part about my job I like the least, but I like that for me, it’s sort of the culmination of all the work to figure out how things work, how how all the pieces work together within a particular product or project. And then the output is the writing piece, which is maybe what I spend the least amount of time or the least amount of energy on by doing more of the research on the front end. So that’s my my origin story, if you will.
Kelly Fitzpatrick: That’s a great origin story, and I love the idea of how many writers actually hate the process of writing or have a love/hate relationship with it. I definitely live in that world as well. And as you were speaking, I just realized that we’ve all chatted before like planning calls and things like that, but you went from web developer to tech writer and Kate in some ways went from tech comm professor to web developer. And I both helped coach you from your web development jobs to come work with me in some capacity. So woo hoo!
Kate Holterhoff: Is that a coincidence?
Kelly Fitzpatrick: Maybe…
Kate Holterhoff: It can’t be!
Kate Holterhoff: So, Abby, you work for VMware, but your job is to work on open source projects. For instance, you’re currently working on Kubernetes. Can you tell us more about what it’s like to collaborate on open source?
Abigail McCarthy: Yeah, it’s been a really great experience. So I’ve been around, more of a lurker in the Kubernetes community for a while because it was related to other products that I was working on or other enterprise endeavors that I was working on. And then a couple of years ago, I got the opportunity to switch being completely into the open source world and helping other CNCF and Cloud native projects with their documentation. And that led me back into the Kubernetes community and being able to be there a little bit more full time than I had been able to do previously. So it’s a really wonderful community from my experience. There’s been a lot of really great people that I’ve got to connect with and learn from. When I first got engaged with the Kubernetes community, it was when things were just sort of forming and I got to sit in a lot of the early SIG Docs group. So Kubernetes is organized into different special interest groups, and they have one dedicated to all of the pieces of documentation. So the website, documentation, localization, all the things that go into documentation for a project.
Abigail McCarthy: And I got to sit in when — sort of got involved a little bit — when that piece of the project was formalizing and setting up processes and figuring out how documentation was going to work within the Kubernetes project. And that was also when I was just starting out as a writer myself. So I got to learn about that process of setting things up and how to do things at scale, what processes work, what maybe doesn’t work, how to be inclusive, how to really engage with people and set up an environment that people will want to be a part of, in this case, documentation, but in part of the open source project. So I feel like I’ve been really fortunate to be able to be a part of Kubernetes and really learn from people who are pioneers in the field, in open source. So it’s been really great.
Kelly Fitzpatrick: Yeah. And I know you’ve given a talk at a Write the Docs conference. I’m getting started with open source and we’ll get a link to that for folks who want to see your brilliance on that topic. I think those are publicly available as well. But I also know that you went to your first in-person KubeCon just this past fall in Detroit. I just wanted to know what are your thoughts on KubeCon from that documentarian perspective?
Abigail McCarthy: Yes, I was able to go to KubeCon and it was amazing. I had been trying to go for a long time and for personal reasons — lots of other reasons — I was not able to attend until just a couple of months ago. And it was really a wonderful experience. Like I said, I have known a lot of people in the community for a while, so I got to actually meet them in person and connect with them outside of the Zoomscape. So that was really nice. I think from the perspective of a documentarian, it’s always really pleasantly surprising how engaged folks in the community are with documentation. It’s something that people think about, ask about, are really excited for things that are going on within the documentation group. And I really think a big positive, and benefit within the Kubernetes landscape is that they have made documentation a big part of the release process — the development cycle. And I think that that has led to a lot of helpful adoption of Kubernetes because they do have good docs processes, and it’s really nice to see people within the community actively engaging and being part of the documentation in addition to the code and the other aspects of the project.
Kate Holterhoff: The sort of enthusiasm that you’re seeing in the Kubernetes community really reflects a lot of what the series is supposed to be about. It also is something that we see at RedMonk pretty broadly. I guess what I’m really curious about, though, is why docs are so critical in open source projects in particular.
Abigail McCarthy: Yeah, I always think docs are important, which is a good way to stay employed. It’s to be advocating for docs to be an important part of processes. But for open source, I think they’re really critical because they are the main window or the main avenue that folks will be able to understand what your project is about and how to use your project, why they should be involved, why they should care, why they should talk to their friends, why they should talk to their coworkers, to their managers, and say, this project is really great because it solves X, Y, Z things. So documentation in particular is, like I said, the main avenue, because you don’t necessarily have all of the resourced teams that you would as part of a company or a product team. You don’t have a marketing team necessarily unless you’re part of a really big project, which not everyone — a lot of those projects aren’t. You don’t have a marketing team, you don’t have a sales team, you don’t have people creating additional collateral and interest within your project. It’s really just what you have written in your documentation and what you can show people and highlight to people within your repo or wherever your code base is. Or if you have a website, if you’re able to create one. So I think that that’s why it’s something that is really critical. If your long term goals for your project are around adoption or creating like a big community, you’re going to need to have invested in documentation so that you can get the word out about your project and have a place for people to really engage and understand what you’re trying to do with your project.
Kelly Fitzpatrick: One thing we hear about all the time are the challenges of maintaining open source projects and finding contributors and maintainers and the like. What are some of the challenges that you specifically have seen with open source and documentation?
Abigail McCarthy: Yeah, I mean, I think those are really the biggest ones that you mentioned. It’s still trying to find people who have time to invest in your project and also having the time yourself to invest. A lot of things I hear — a lot of talk I’ve heard in open source in the past couple of months has been around creating mentorships and a mentorship avenue for folks. (I keep saying the word avenue. That’s like my hot button word for the day.) [laughs] — Creating those avenues for people to get into your project, get invested, and then also climb your contributor ladder from being within your community, to contributing in some way. And then learning about your processes and then taking on more of a leadership sort of role and carrying the torch forward as part of a maintainer set.
Abigail McCarthy: So I still think a problem across all areas in an open source project is finding people who are able to stay because it is often volunteer based. People have to do nights and weekends, which is not always sustainable for a lot of people. It’s not always practical for people, which is completely understandable. But it is a big challenge in all areas. And I also think specifically for technical writing, it’s something technical writers are aware of as an option for contributing people to do. Technical writers can get involved in open source projects too, but I think there could be also some more just general advocacy and outreach to technical writing communities to get folks a little more engaged. And I think there might be a little more pieces to do — a little more bridge work to get folks who maybe don’t have as technical of a background more help within certain projects to get to the point where they feel more comfortable engaging in a more long term, sustainable way.
Kelly Fitzpatrick: See? The avenues and bridge work metaphors are working very nicely together.
Abigail McCarthy: A lot of civic engineering going on in open source today.
Kate Holterhoff: Well, to expand on that idea of bridge work, are there any processes or advice that you found to be particularly helpful?
Abigail McCarthy: Something I would say process-wise within technical writing and open source… I think a big thing to learn or be aware of is the docs-as-code sort of methodology to think about how — and that’s basically the thought that you should treat your documentation in the same way that you treat your code. So it should live within the same repo as you have your code or very close to where you have your code. Go through the same processes, same development cycle, review cycle, merge whatever whatever cycles you have or whatever processes you have that you apply to your code. You should do the same within your docs and everything should follow the same development cycle, release cycle, same level of engagement from people across your — whatever team you have. Hopefully it’s a team, maybe it’s just one person who is your maintainer for your project. But whatever processes you have for developing your code should be applied to your docs. And I think that that’s something that particularly resonates with open source projects because it’s for free. You are using the same the same tools that you are using to manage code. You don’t need to have an additional code – not code — editor or additional tools or whatever to manage your docs. Everything can be managed in the same way. So I think that’s something that’s really important to know about. If you are somebody who is interested in technical writing and technical writing and open source, that I would definitely recommend getting a little more information about that and getting familiar with those processes.
Abigail McCarthy: I think not specifically processes — like I was talking about docs-as-code — but just like generally with getting involved in open source, I think the best advice I can give is to just do it. No — it’s just try to find a place to get involved and know that not every community that you start out –every community that you enter into– it might not be a good fit for you. But I think you should still not get discouraged, still try to participate, join community meetings, join slack channels, anything you can do to get a little more information about the project that you’re interested in to see if it’s a right fit for you and then continue just trying to get more involved and just really reach out. It can be really uncomfortable. Like I said, I was a lurker in the community for Kubernetes for a long time, so it can be really uncomfortable and it might take a while for you to feel comfortable to do that. But I definitely would encourage people to go out and find a community if they’re interested in contributing to open source and just sort of put yourself out there, even if it’s uncomfortable. I promise you people will be receptive and happy that you’re there. And if they are not, then that’s not the community for you and you can find someplace else to move on to.
Kelly Fitzpatrick: Yeah, agreed. And Abbie, you talked a bit about docs-as-code, which is something we’ve talked about before on The Docs are In clearly and probably needs to talk about more into infinity. But another thing that we’ve heard a lot about is the idea of treating docs as products. Can you talk a little bit about that?
Abigail McCarthy: Yeah, for sure. So I feel like sometimes when I get talking about docs, I’m kind of like the meme of the guy from Ancient Aliens where he’s just like *aliens*, but I’m just like, *docs*, you know? And that’s kind of how I feel about docs in general. Like it is the root solution for all of the things in my personal opinion. So I do think that it’s very important and very worthwhile for you to spend the time to treat your documentation as it is a product, or at least in step as the same level of everything else you’re doing with your product or your project. I think if you take a step back and go through your whole development cycle or release cycle or whatever it is, and just note all the places that you have to write things down, either in planning, your road mapping, creating issues, figuring out how things work, or doing proposals or, you know — I guess proposal is probably the most universal word of how you want a feature to work and then all the other pieces that go into it. When you have a release, you have your release notes, you have communications that go out. If you have a presence on social media or on Slack or on some other sort of — some way that you tell your followers that a new release has happened — in email. All of those things are pieces of documentation. Maybe not in the more traditional sense of the word of documentation, which is only user guides, tutorials, reference guides, or things that are in the docs section of your repo or on your website. But I do think that all of those things are really important for your project, and they do count as documentation and pieces of writing that you or someone within your community should be responsible for at some point along the way. So I think that that is why it’s worthwhile to create the culture of docs, which I think I’ve mentioned before, to keep documentation on par with all of the project work you are doing — being the code work that you are doing. So that you can make sure that all of these pieces go together and they all have kind of a through line so that when you get to your release or get to wherever you are, you’ll be able to present your users or be able to remember yourself what was happening when you were doing something along the way.
Kelly Fitzpatrick: Yeah, I love that. The Culture of Docs idea. How do you how do you elevate docs and not just to keep them in sync, but to make them more visible and use them as a tool?
Abigail McCarthy: Mm hmm. Exactly. Yeah. I feel like I heard that from someone else, so I’m probably not giving someone proper credit, but I like the idea of creating a culture. Like a positive culture. And it’s not like a chore because a lot of times some people have that perception that documentation is a chore or an afterthought or whatever. But if you start it right from the beginning and say, These are the things that are important to our project, it will just become ingrained in the layout of your community anyway and just become a part of how people work within your community.
Kelly Fitzpatrick: Well, Abbie, thank you so much for joining us today. I know that we’ve only scratched the surface in talking about open source docs, but your expertise and your time is very much appreciated.
Abigail McCarthy: Yes. Thank you so much for having me. It was a true pleasure to be able to chat with you all. Thank you.
Kate Holterhoff: And with that, the docs are out.
