If you are interested in the prospect of creating a “culture of docs” in open source software (OSS) communities–or if you just love civil engineering metaphors–this The Docs Are In episode is for you. This time around Kate and I interview Abigail McCarthy, who has some very fancy titles: 1) Staff Technical Open Source Communications Manager at VMware and 2) Kubernetes SIG Docs Localization Subproject Lead. Abbie landed at VMware through its acquisition of Heptio (a company built around Kubernetes), and describes her day job as such:
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.
We then jump into how Abbie got into tech writing (TL;DR: “accidentally”), and it is worth noting that I had the great privilege of working with Abbie at her first tech writing gig at Apprenda (where she began engaging with the Kubernetes community). Having both Abbie and Kate (who I worked with in our pre-Monk days at Georgia Tech) in the same docs-related conversation was an absolute delight for me, and we cover a LOT of ground in the remainder of the conversation:
- Actual writing is the part of tech writing Abbie likes least; she prefers figuring out how all the things work, how all the pieces fit together, and sees writing as the output of these processes.
- Documentation as an avenue into OSS and Abbie’s own path from an OSS “lurker” to active community member. Abbie also recounts witnessing early on how the Kubernetes SIG Docs group went through the process of setting things up; she saw first-hand what works, what doesn’t, how to be inclusive, and how to set up an environment that people want to be a part of.
- Abbie’s trip to KubeCon in Detroit this past October, where she got to interact with members of the Kubernetes community “outside of the Zoomscape” and was delighted to see “how engaged folks in the community are with documentation.”
- Some of the challenges Abbie has run into with OSS docs, which include getting and keeping folks involved with OSS documentation.
On this last point, Abbie calls out the importance of creating “bridges” to help get folks–especially writers–more comfortable engaging with OSS projects:
I think there could also be some more 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.
We then get to the importance of creating a “culture of docs,” which Abbie describes as such:
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.
She then elaborates on how influential this can be on the larger community:
I like the idea of creating a culture–a positive culture–and it’s not a chore because a lot of times some people have that perception that documentation is a chore or an afterthought. 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.
I love the concept of a “culture of docs” and also that a project as successful as Kubernetes has created a strong docs culture within its larger community (and managed to bring a documentarian like Abbie into the fold).
You can watch the video of this conversation below or see the full transcript and related links.
Disclosure: VMware is a RedMonk client; however, this post and the RedMonk video mentioned in this post were not commissioned by any entity.
No Comments