In this episode of The Docs Are In, the excellent Alyssa Rock (Staff Technical Writer, VMware; Community Manager, The Good Docs Project; Coordinator, Write the Docs Quorum Program) drops in to chat with Kate and Kelly about the many, many hats she wears. Alyssa discusses her pathway into tech writing (it led through film studies!), some of the good things happening with The Good Docs Project, and her work on the Salt Project as part of her day job with VMware. Also of interest: how to empower folks who are not technical writers to produce effective documentation (while teaching them about tech writing along the way), and how to make open source “sticky” by helping contributors to get started with projects while also creating supportive communities around them.
This was a RedMonk video; VMware is a RedMonk client, but this video was not commissioned by any entity.
Resources
Alyssa’s blog (including a post mentioned in the video on Getting started in open source as a new technical writer)
VMware blog post on building better documentation practices for developers
Rather listen to this conversation as a podcast?
Transcript
Kate Holterhoff: It is my great privilege to welcome Alyssa Rock, Staff Technical Writer at VMware, Community Manager at the Good Docs Project and Coordinator for the Write the Docs Quorum program to this episode of RedMonk’s Docs are In series where we discuss everything related to docs from academic doctorates to documentation and technical communication. My name is Kate Holterhoff, analyst at RedMonk. And with me is KellyAnn Fitzpatrick, senior analyst at RedMonk. Thank you so much for joining us today, Alyssa.
Alyssa Rock: Happy to be here. Thanks.
Kate Holterhoff: All right. So let’s begin with some of your history. How did you get into tech writing?
Alyssa Rock: Well, I came into technical writing from academia. At the time, I was interested in getting a PhD in film studies. I also did concurrent degrees in English and things like that. Those have always been the themes of my life. But mid-way through my PhD program, I just was like, I don’t think I love this anymore. I think I want to get an office job. And so I was open to many different roles. But the one role that I was able to get was as a technical writer working for Yahoo! So that was my first technical writing job. I did that for a little bit until Yahoo! fell upon hard times and laid off a bunch of workers, including me, at which point I went back to academia for a little while, did some teaching, and then about maybe six years ago, re-entered technical writing. And I’ve been there ever since. And then about three years ago, I started working for a company that started as an open source project, which is how I got interested in open source documentation in general.
Kelly Fitzpatrick: And you are clearly in good company. Both Kate and myself, of course, are kind of like, are we in academia or are we in tech? Is it both? Which is one of the reasons we have this series.
Alyssa Rock: Yeah! Awesome.
Kelly Fitzpatrick: Yeah. And kudos to you for getting out of academia early on and understanding that like, okay, I don’t want to go through the whole thing — because PhDs, they are not easy things I feel like and it’s — but they can be so hard to leave. It’s almost like you don’t — it’s a hard decision to make.
Alyssa Rock: I think it’s difficult because of the sunk cost fallacy when you’ve already invested so much time and energy and you do have a certain amount of passion to go into a field like that, it can be difficult to say this isn’t right, this isn’t working out for me. And to kind of have that self awareness to step away. But yeah, I still love that and miss that world in some ways. But I’m happy in technical writing.
Kelly Fitzpatrick: Yeah. And like for me, there’s always this overlap between teaching and the stuff I did in academia, in research and especially technical writing. So I almost feel like you almost get the teaching fix sometimes when you’re walking someone through how to do something for the first time.
Alyssa Rock: Yeah, absolutely. One thing I did enjoy about the teaching path when it came to academia — and that was the part of that career that I enjoyed most, was the teaching part. But what’s interesting is maybe it’s because I have a slightly more introverted edge or something like that. I always enjoyed crafting the lesson and designing an experience for somebody to have. And so I enjoyed the intellectual side of preparing a lesson plan and getting excited about how the students would experience it. And then actually teaching it in class was just executing the plan. So I found out I enjoyed the creation of the lesson a little bit more than teaching per se. And so technical writing can be a really good blend of that. You get the thoughtfulness of thinking through, how can I design an experience that will help somebody really engage with this product? And by the time they’re done reading this documentation or working through this tutorial, they’ll have the knowledge or the skills that they need to be empowered to then do something with the tool that will solve their problems. So I still get that out of technical writing, which is really fun because that’s the part that I enjoyed most about teaching.
Kelly Fitzpatrick: Yeah, same. So shifting gears a little bit, you work for VMware, but you are also very much involved in the Good Docs project, in terms of — which I love, because it’s not just about creating documentation, but this is a project about helping other people create better documentation, if I’m not wrong. What can you tell us about this project and who the audience is for the project?
Alyssa Rock: Yeah, so the Good Docs project is about three years old now. Maybe it’s coming on its fourth year. It started as a project that was designed to just empower in particular non-technical writers. But obviously there is an interest from technical writers in the project. We wanted to empower non-technical writers who maybe don’t have the tools or the expertise or the background necessarily to write effective documentation. What we wanted to do was to make it easy for them to lower the barrier to entry and make it easy for them to produce high quality documentation without having to go and get a degree or study technical writing forever. And so the main goal that we have for the project is to create templates for a variety of content types that you can drag and drop into your documentation system as needed. And in addition to the template that helps you create the documentation for whatever content type you’re working on, be it a tutorial or a how to, or in open source, a read me or a contributing guide. Not only do you get the template that you can instantly deploy in your system, but you also get a helpful guide that teaches you a little bit about technical writing as you’re filling it out and tells you a little bit about best practices and the right way to research and approach that content type as you’re writing it. So it’s both empowering people to overcome that blank page with a template and start writing and get them, you know, along that process, but also teaching them a little bit along the way. So really, it’s just about kind of helping people create better documentation by making it easier to do so.
Kate Holterhoff: I like that framing of enablement. I mean, I think that really gets to your interest in the pedagogical sort of extensibility of your time in academia and how you really recognize what it is that you wanted to take away from that experience and do for the rest of your life. And I think that’s such an exciting way to talk to folks who’ve had sort of mixed experiences in the academy. So I guess I’m curious specifically about your experience with the open source community. Can you talk at all about some of the challenges, maybe opportunities of working with that group of collaborators in particular?
Alyssa Rock: Yeah. So let me tell you about the work that I do at VMware. For the past year I’ve been working — so that company I mentioned that started as an open source project. The company used to be called SaltStack, and then they got acquired by VMware. For a long time I was working on the proprietary side of their software, but I’ve always been very attracted to their open source community and they didn’t really have a technical writer and hadn’t had a dedicated technical writer for the ten years that the project had been in existence. And so there was a lot of work to be done, and I was really passionate about joining the project and helping them to improve that documentation.
Alyssa Rock: So about a year ago, I was able to switch over from the proprietary side to work in the open source side. And there’s a lot of things that I really enjoy about working with open source communities like that. Just so you know, the Salt Project is a Python based configuration management tool and is a huge project with probably about 5000 contributors. So very, very large software project. What’s kind of fun about working with an open source community that you don’t get as a traditional technical writer is that community management piece where you’re interacting pretty directly with the very people that are going to be reading and consuming the documentation and in some cases working on the documentation with you. So that’s a really interesting mix that a traditional technical writer doesn’t get. So you have to have a lot of soft skills, people skills. You have to be really flexible, you have to be very patient and you have to do things that traditional technical writers don’t always have a ton of experience with. But along with that comes a lot of unique challenges and opportunities.
Alyssa Rock: I was– I kind of blew my manager’s mind the other day or recently because we have a Salt Docs working group. We do a lot of our work by meeting once a week as a group and anybody who wants to join my group in the project and work on a documentation project can join. And typically we get a lot of new technical writers who want to break into the field of technical writing and want to work with a more experienced technical writer to get some mentorship while building skills and being able to have something to show a potential employer. What’s exciting about that opportunity is that I get to have a lot of people join my docs working group that I wouldn’t have met otherwise. And they just kind of come and say they want to work, and I find a task for them to work on — and in a way that I’ve grown my team by about four people over the last couple of months, whereas a traditional technical writer has to go through a hiring process which can be long and arduous and difficult, and maybe you don’t get the same sort of resources or help that you get. But I’m able to attract a lot of different technical writers to my Salt Docs working group into my Good Docs project as well. And I’m able to extend what I’m able to do because I have this working group that is taking on a lot of the projects that I personally haven’t had time for or bandwidth for. So we’re able to just kind of essentially triple the amount of work that I was able to do by myself as a technical writer, just from people volunteering and wanting to get some experience and some mentorship. And that kind of blew my manager’s mind. She was like, wait a minute! She would always ask me questions like, they’re working for you for free? I was like, yeah! They just want to build their skills and be mentored and contribute to a project that they care about. And she was like, but they just come and they just want to work with you? And she was just — she was surprised but delighted that we were able to extend our capacity and do so much more with less because we work in open source. So that’s one of the exciting opportunities and I can speak more about some of the challenges that come with that, if you’d like.
Kate Holterhoff: Yes. Yeah. Please, let’s hear more about this. This is something where you clearly have this deep knowledge. And I’m so excited to hear more about what it’s like in the trenches.
Alyssa Rock: Yeah. Let’s see. So I think one of the trickiest things about working in an open source environment is that you have to be very flexible because people come and go. Some people like, for example, at any time one of the members of my Salt Docs working group might get a new job and say, see ya, I can’t finish the documentation project that I’ve been working these last several months on. Which would mean either the project just kind of goes back into the backlog and doesn’t get worked on or I have to pick it up or somebody else has to pick it up or something like that. And so you have to be really flexible and be able to accommodate anything happening. So at any point I have to be ready to take on new writers and have tasks for them to work on. So I’m always working on building out a backlog of documentation epics and a roadmap of what I would do if I had more resources. And because I have that backlog of things that I would do if suddenly I got a lot more people working for me, when somebody does join, I have something for them to look at. I can say, look at the backlog, look at this roadmap, see if there’s any of these projects that interest you, or sometimes I’ll just have like an in depth interview with them and talk about, what are your goals for contributing? What are you hoping to get out of your time here with us at the project? And I’ll see if I can find a task that matches your needs and what you’re hoping to get out of it, which increases the chance that they’ll stick around because it has some intrinsic value to them.
Alyssa Rock: So for example, I have one technical writer who wanted to join too, and she had dual interests in both UX and technical writing. So I’ve had a project in my backlog for a while that really needed to be done, which is developing the user personas for our community and identifying who really is our target audience, what are their needs and what’s the ideal journey that they should have through our documentation so that we could then design a documentation landing page that will meet their different needs. So because I was able to talk to her and understand what she wanted, I could find a task from my backlog that matched her professional goals and the kind of experience that she wanted to get.
Alyssa Rock: And then she does the work and I just kind of coach her and mentor along the way, and it’s just been exciting to see how she’s grown and develop professionally. She’s been working on that project, but if she got a job tomorrow and had to leave the project because she was too busy with time, you know, at least retain the artifacts of what she was working on. And I’ve been following her journey along the way to where I could pick it up or could hand it off to a new person and be able to get them up to speed with with how far she took the project up to that point. So it’s a lot about being flexible and also matching tasks for what — meeting people halfway, I guess? Like when somebody comes to you and says what they want, you help them find something that matches what they want, which builds intrinsic motivation and “stickiness” in your docs working group or in your project and also extends the capability of what you would have been able to do if you didn’t have that help those resources, if that makes sense.
Kelly Fitzpatrick: It does. And I know that you actually contextualize this as, oh, you know, people are willing to do this work without being compensated in money. But the flip side of it is, we’ve heard about things like marking issues that are good for first contributions to your project. But what you’re talking about is so much more individualized in terms of not just marking off — here’s a here’s a good one to start, but finding out what a potential contributor is interested in and just kind of putting together a plan of things to work on. And I, I think that is, that is fascinating. And for me, that is like one of the best uses I can think of, of that almost like pedagogical impulse that you seem to have from just kind of your past experiences.
Alyssa Rock: Well, thank you. I really appreciate that. One thing that I do want to mention. First off, you made me think of a lot of different things, so I’ll make sure I cover the two things that I thought of while you were talking, which is that the Good Docs project, we’ve been kind of taking that model and taking it to the next level, which is where we have regular welcome wagon meetings where if somebody joins our project, we ask them before they can get access to a repository or get assigned to their first task, we ask them to come to a meeting that the first 15 minutes will be about what’s the project like, “What are some of our pieces of etiquette that we want you to follow as you’re contributing? How to contribute for the first time? Here’s the resources that are available to you. Here’s our code of conduct…”, things like that. And then the second 15 minutes, everybody is paired off with an individual “welcomer.” And that welcomer will have that discussion with them. Will talk about “what are you hoping to get out of contributing to our project? What are your interests? How can we match you with the best first task that you might have?” And then based on that conversation, do a warm handoff to a working group leader.
Alyssa Rock: So engage in the conversation and then we say, “Hi, this is so and so they joined our project. Here’s a little bit about their background. Here’s what they’re hoping to do with the project. We thought this task might be good. Now, Working Group Leader, how about you take over and see if that really would be the best task for them, given what you have in your backlog or what you’re trying to accomplish.” So, I love that kind of warm handoff model where it’s good. But what I think is important about that is, like I said, building up the stickiness of your community, which is about making it so that people want to stay and stick around and make a long term contribution. And one of the keys to that is fostering intrinsic motivation. Finding something that somebody is getting out on an intrinsic level, even if it’s just, “I have friends in the project tonight and I socialize with them!” But what makes the project sticky, I think, is that we’re all supporting each other in our professional goals. We’re all trying to be better. We’re trying to be better writers or better developers or whatever it is we’re trying to skill up with, and we’re all in this together supporting each other, you know?
Kelly Fitzpatrick: So, Alyssa, I feel like you wear so many different hats between your work at VMware and your work with the Salt Project and the Good Docs Project and even the Write the Docs community. One thread that we’re kind of seeing through all of this is the potential of open source itself as a kind of alternative career path or a version of a career path that most people don’t think about. Can you talk a little bit about that as a way into tech?
Alyssa Rock: Yeah, no worries. Back in the days when I used to kind of lurk and contribute to the technical writing subreddit, which I haven’t done in quite some time, it seemed like the most common question that kept coming up on that subreddit, which is how can I break into technical writing? How can I start my career in technical writing? A lot of times it was either people fresh out of college who didn’t have any work experience, or it was people who had an alternate career and wanted to move into technical writing. And I found myself repeating the same advice over and over again that I eventually turned it into a blog entry. But basically I do really feel like open source is a clear pathway into technical writing. Let me give a caveat because I don’t want to betray academia as a fellow academic and say that it’s not a replacement for a college degree. I still think there’s a ton of value in getting a college degree. And so I’m not suggesting that college degrees don’t matter because that can be a really important way to build the critical thinking skills and things like that that you need to make it in technical writing. So I don’t want it to sound like I’m saying don’t get a college degree. But if you have a college degree in a different field or if you have no work experience, then open source, can can very definitely be a pathway into a career in technical writing. And so one thing is if you turn the tables and think about an employer looking to hire a technical writer, one of the things that they’re particularly looking for is they want to see proof that you can do the job and they want to see some tangible proof.
Alyssa Rock: They want to hear a real stories or see real evidence that you’ve been able to do technical writing. And, a lot of times you do get your first opportunity through your network. You get to hear about opportunities through the people that you know, either casually or through loose connections, because you’ve got to admit that employers also care about, “will this person be enjoyable to work with? Will I like working with them?” So sometimes having a connection through a social network can be a very viable means of getting a job. And what’s great about open source is that it gives you both. It gives you a social network. You start to develop those professional networks and relationships with people who know other people and can help you find your first job or hear about a job in one way or another. They also get a chance to work with you one on one and see you up close and in action the way they would work with a real coworker and so they can vouch for you on a deeper level than maybe — just the same as a coworker would. And then most importantly, it gives you the real skills and the tangible proof that you actually can do the job. Like I mentioned with people who join me at the Salt Project, they’re doing real documentation projects and building the real skills and knowledge in both the domain area, meaning the the subject matter that they’re writing about and that domain of expertise and also in documentation at the same time, and getting a deeper, really well grounded, practical experience working with the tool.
Alyssa Rock: It’s kind of like having an internship in many ways, but it’s one that you volunteer for. And then and then we work with you, that kind of thing. You just show up and we say, Yeah, we’ll take you. So as long as you abide by our community rules, we’re happy to have you join our project and put you to work. And through — I haven’t seen any through the Salt Project get jobs yet, but just because our working group is still very young and — but I’m sure we’ll have a few job successes to share from that. But from the Good Docs project, we’ve had definitely for sure, at least four people who would not have gotten their jobs if they hadn’t joined our project. And I’m being very conservative with that number. I think the number is actually higher. I’m just going with people who I can connect the dots and say, that person definitely got the job because of our project. So I really do think that technical writing can be a valuable or sorry — not technical writing — open source can be a valuable way to get into technical writing or software or anything that open source can give you experience with.
Kelly Fitzpatrick: Yeah. And to your point about this is — you’re doing actual work when you’re committing to an open source project and often using tools that you would use in a more kind of paid job situation. Where I know we talked about open source versus academia or getting a degree. One of the concerns I see a lot of the folks that I know who are going through computer science programs or even bootcamps is “are the things that I’m learning and are the tools that I’m using what I will actually use in the job?” And I think in open source, you can you can actually say, well, this is this is stuff that people are using out there in actual tech industry, tech industry work, even if it’s not what everybody is using everywhere. So it does have that kind of credibility that you don’t always see in more academic or bootcamp-like situations.
Alyssa Rock: Oh, I totally agree. And not only that, but it’s also like on the cutting edge of what’s being developed, what will become tomorrow’s technology. So you might even get a little bit ahead of the curve. And working with technology that is soon to be implemented and adopted. So yeah.
Kate Holterhoff: Well, on that inspiring note, I think, let’s thank Alyssa for joining us on this episode of The Docs are In. Thank you so much for being with us here today.
Alyssa Rock: Oh, absolutely. It was a joy. Thank you so much, Kate and Kelly. It was wonderful to be here.
Kelly Fitzpatrick: And with that, the docs are out.
