Search results

Podcast: Users as producers of knowledge -- conversation with Nupoor Ranade about how tech writer roles are changing

by Tom Johnson on Mar 29, 2020
categories: academics-and-practitioners • podcasts • api-doc

How can users shape and influence the documentation you're producing? In this podcast, I chat with Nupoor Ranade, PhD candidate at North Carolina State University, about how the roles of technical writers are changing. Instead of writers authoring content for passive users, users are actively directing and shaping the knowledge that writers produce. In this podcast, we look at ways docs-as-code workflows are facilitating that shift in roles. This podcast is more of a conversation, where I first ask Nupoor a series of questions, and then she asks me questions. There's also a transcript of the podcast.

Listen here:

Topics explored during the podcast

We explore some of these questions during the podcast:

  • Docs-as-code approaches in the workplace
  • How writers’ responsibilities have changed within the docs-as-code workflow
  • Skills writers need to develop to succeed and thrive in these changing roles
  • Focusing on the “changing nature of audiences especially in participatory networks, where audiences are not only the consumers of information but also the producers of knowledge” (Introduction to Nupoor Ranade)
  • How audiences for dissertation research can co-create the research and shape the dissertation content

Participating in the Nupoor’s research

If you’d like to be interviewed for Nupoor’s research, reach out to Nupoor at [email protected] or on Twitter at @nupoorwriting to indicate your interest. She will then probably set up a time to interview you for her study on audience participation in software product documentation. The interview might consist of the following sample questions:

  • Do you develop content collaboratively for internal/external documentation?
  • Can you describe your role as a business or professional communicator with the organization that you are part of?
  • Do you have access to users of the project/s you work on either through usability tests, content development processes, analytical software or any other means? Describe in detail.
  • How do you solicit contributions internal and/or external entities? For example, content edits by product developers or external users on GitHub, tools that allow you to record user interactions, and so on.
  • Do interactions with users generate content? Is that content used? How do you handle that content? Do users know that they can participate in content development?
  • How long have you been working with projects that use participation from users? Do you think it has changed your role as a business and/or professional communicator? If so, how?
  • How do you manage collaborative projects? (Methodology – agile/kanban/scrum/scaled agile/waterfall)

Resources mentioned during the podcast and other resources

Transcript

The following is a machine-generated transcript that has been edited for readability. Keep in mind that speech, especially during conversations, isn’t the same as writing and doesn’t read the same. We’ve tried to make it more readable here.

Tom: You’re listening to a podcast from I’d Rather Be Writing. My name is Tom Johnson, and today I am speaking with Nupoor Ranade, a PhD candidate at the North Carolina State University. Nupoor, can you introduce yourself a little bit? Tell us what program you’re in and what you are studying.

 

Nupoor: Hi, Tom. Thanks for having me. Sure, I’d like to introduce myself here. I’m a PhD candidate in the Communications, Rhetoric and Digital Media program at the North Carolina State University. I joined the program in 2017 while I was completing my coursework and my prospective for my dissertation. At that time I was a “PhD student” or a doctoral student, and now that I’m in the last phase, which is my thesis or dissertation phase, I’m a “PhD candidate.”

I work with Dr Jason Swarts. He’s my advisor and the chair of my dissertation committee. During the PhD I interned with SAS in their publications department. I did a few other research assistantships and also teaching assistantships during which I taught courses in digital rhetoric and technical communication.

My research interests fall under technical communication, user experience research, and audience studies or user generated content because we have a lot of overlap among each other. Right now, I’m in my dissertation phase and basically in the data collection phase for my dissertation.

 

Tom: Great! Now for listeners who don’t know, actually in 2015 I met you at the tcworld conference, in Bangalore. I remember at that time you hadn’t entered your PhD program, right? You were still a student working at a company – I think you said Tibco. You were very energetic and really into tech comm. I remember you had a high energy level and interest in tech comm, and I kind of thought you would just follow the corporate route like most people, jumping from one company to another, climbing the ladders or whatever route we take in our careers. But instead you went the academic route — you entered a master’s program at North Carolina in tech comm, and then a PhD program, and now you’re entering the final stages of that with your dissertation. I’m just kind of curious, what prompted you to pursue the academic route rather than the traditional corporate route?

 

Nupoor: Yes, I remember we met at the tcWorld 2015 conference and you were the keynote speaker. I was really excited to see you there. At that time I was a recent computer engineering graduate student and had just graduated from undergrad, and I was working as a technical writer with Tibco software.

I wanted to grow in the career, but a lot of my interests were with the research aspects of tech writing more than just writing conventional documentation. I wanted to do more things like user experience or usability tests and those sorts of things. But there wasn’t much scope. The other route was to pursue an education, which would help me build that research portfolio. I did not have that research grounding at that time, and India didn’t have formal technical communication courses either. That’s why I decided to pursue a degree here in the United States. I moved to the US in 2015 for the masters program at NC State.

In the program, we had a variety of courses. We had advanced technical writing, theory of technical communication, rhetoric of science and technical communication. These courses taught us how the technical communications field was really formed, what is the history of it, and so on. What I learned in my program seemed to have a big disconnect from the work that I did in the industry before I came into the program. I started to understand the field in a completely different way – understanding the theory and underlying concepts behind it for the first time. It wasn’t the way I had learned to do technical writing on the job in a day-to-day practical way.

In general there’s a disconnect between the two. There are some things that academic research has that are extremely good and extremely important, which are not talked about as much in the industry. At the same time, there are some things in the industry, like the tools and technologies, which are not discussed in academia.

And I wanted to fill the gap between these two, which is why I decided to continue research and the way to do that was pursue a PhD program and become the professor in the classroom who teaches those things to students, to the next generation of technical communicators.

The second reason to pursue a PhD was the visa issues. Not many people know about this aspect. Technical communication careers in the US are not classified under the STEM (science, technology, engineering, and mathematics) and as such, the work permits are harder to get. The tech comm students get only a year to apply for the work visa while engineering graduates get up to three years to apply for the work visa.

The insecurity, you know, the idea of losing the opportunity of staying in this country or continuing working with the organization that you’re part of, is difficult for some students to navigate, which is why they turn to PhD programs — it’s better for the visa or the work permit situation. We’ve got a non-exempt track, which is just a different track, being an academician. So it’s about the more security granted to different folks. I wanted to stay in this country, continue research, and not go back to doing what I was doing in India. Those were the two main reasons.

 

Tom: Wow. That’s really interesting. I mean, this whole idea that you’re working in a company, but then when you switch gears into an academic program you realize there’s a huge disconnect between what you’d been taught on the job versus the theoretical foundations you were learning, is interesting to me. Do you plan to go back to India and grow the industry there with what you’re learning in your program?

 

Nupoor: I don’t see myself doing that at least for the next five years. Currently, my focus is to graduate and perform more research here. In India, a lot of formal education programs in tech comm are growing, or at least people are starting up some of those programs and they go to universities. So if that happens, that would give me a good space art, a good platform to go and like share my research with students as well as the industry. At that point I would make the change.

 

Tom: You’ve kind of surfaced a topic that I’ve written about on my blog before, and it’s this divide between academia and the industry. I like your depiction here of how the industry might have more emphasis on tools and tech, and how on the flip side, the industry or the corporate world often doesn’t have the emphasis on the critical analysis or the rhetorical thinking that is often emphasized in academic programs. I’ve often kind of lamented this divide in a lack of communication between the two, the disconnect.

And so I’m excited to see your focus here and that you’ve actually been pretty successful in your research. I saw that you won a student research competition at SIGDOC. You won an award recently. Can you tell me a little bit about that?

 

Nupoor: Like I earlier mentioned, one of my research focuses this year is that experience and usability studies. When I was at SaaS, when I was interning there, I had an opportunity to conduct usability testing on their product documentation. At that time, they were revamping it a lot and wondered about how to gather more user input. This was a research projected that I conducted back then, as a way to optimize usability. My focus was on audience research, about how user research helps us dive deeper and how do we analyze our audiences and classify them or look at users from a multidimensional perspective. Dr. Albers, at ECU, talks about looking at your users from a multidimensional perspective, such as understanding the background, understanding other users based on specific characteristics.

I applied that model and wrote an algorithm to conduct a usability test and get more data than we get in conventional ones. I presented that research as SIGDOC, at the student research competition, which is sponsored by Microsoft. I was one of the first to do research on optimizing usability. And I also wrote a proceeding, which was published on their website as well.

 

Tom: That’s great. Yeah. I’ve actually been to a SIGDOC conference. There was one in Louisiana last year a couple of years ago. I met Dr. Albers there. He seemed like a pretty knowledgeable guy. Definitely very well known in the industry, very accomplished. So that’s cool. And I like hearing about your research now. I was reading another article you wrote on the digital rhetoric rhetoric collaborative website, where you’re saying that your current research focus, at least at the time of this article, was to “look at the changing nature of audiences, especially in participatory networks where audiences or audiences are not only the consumers of information, but also the producers of knowledge.”

This perspective about looking at the audience as a producer of knowledge seems to be something that you’re interested in. Can you tell me, is this kind of the focus of your PhD research, or is it different? And tell us a little bit more about that focus.

 

Nupoor: Yes, this is definitely the focus of my PhD dissertation project — to look at this change or transition in the way that we view audiences, but my research also goes back to the disconnect between academia and industry. The idea of docs as code or open authoring is absent currently from academic research, and it’s being talked about all over the place, in the industry.

A lot of companies are moving towards docs-as-code workflows. If you look at the history of audience analysis and academia and academic research or even an industry research, I think they were on the same page where everybody looked at audiences as a fictionalized entity. People always imagined audiences, composition scholars and writers on different fields as well as almost technically communicators. The academic research also points to that.

Eventually we started collecting more data about audiences, like their demographic characteristics, the way they used different tools and the way they gave feedback. All of the research started happening in the industry, folks started thinking about it, how we can collect more and more data, how we can write personas for our audiences, and so on.

Similarly, in academic research people started looking at feedback and personalized personnel development and those kinds of processes. However, I started seeing a disconnect again. Then I started looking back at literature and realized that we do not have much data on using tools like Usabilla to collect audience data, or how to use tools like Google analytics, which allows us to see how our audience is using our information and product documentation.

With open docs, open authoring processes, there is no research about all of these processes. In the industry, I think it is taken more seriously than in academia right now. And they’re constantly innovating with big data and other research. They’re constantly trying to learn more about their users, learn more about that audiences, but sometimes not all of that information gets fed back into the documentation process.

The information gets lost somewhere. For example, tools like Google analytics produce so much data. We know so much about the users, but we have to know how to use that information. We don’t know what to do with it. So it’s just lying around in so many companies. My focus is tying these things together again, bringing that research to academia so that it can get the attention that it deserves.

Also taking the research to the industry to help industry practitioners, what they can get out of it and what to do with it, helping practitioners make sense of the data that they are getting about the users.

 

Tom: Cool. I like this focus on the users actually. I think if we were to boil down what’s a best practice for writing in general, it would be to focus on the user — their pain points, their information needs, what their goals are, what problems are encountering. If there’s anything that drags documentation down, it’s our lack of awareness of that user. So it’s definitely a great focus. And this whole emerging trend about docs-as-code, I think it’s great to hear that you’re including that and focusing on that, because it’s sort of absent from academia. I think that’s a definitely a gap, and these two worlds can connect in better ways. We’re going to dive into that more as we talk.

I know you want to collect data for your research, since you’re in the data collection sort of phase of your dissertation, right? What are you hoping to get help from practitioners about? What kind of data are you trying to gather?

 

Nupoor: Just by talking to practitioners about their day to day activities, I’m learning a lot about the documentation process itself. Earlier we used the waterfall models in most companies for documentation, and now we’ve changed to a more agile approach. As a result, a lot of practices are changing in terms of how writers collaborate with developers and other stakeholders. This collaboration extends to users as well. I’m interested in those practices.

I want to know the ways in which writers try to understand users or connect with users in some ways. For example, I was talking to some groups about how they have a Twitch channel where they stream videos about their games and that’s the way that they can connect to the audiences. The tech writers are doing this because that gives them a platform to directly interact with their users. Other companies have a Slack channel where users can directly ask questions on the channel, and writers participate in the channel and can respond directly to users. Based on those inputs from users, they can make changes to documentation.

This kind of collaborative space that practitioners talk about, their relationship with the outside world of users, their interactions outside the organization, their infrastructure and collaboration channels and what interactions are happening — that’s what I’m interested in.

 

Tom: Oh, that’s good. I think we’re going to have a lot more to say about this collaborative space, especially when we’re talking about docs-as-code, because I think this workflow definitely opens up the communication channels between users and those producing content.

Users can log issues, they can file pull requests. They have a communication point that wasn’t always available previously, at least not in such a public and formalized way. Related to this, I was listening to a podcast from Instrktiv that included an interview with Hans van der Meij. This guy basically spent his life researching minimalism, and he said that one problem technical writers have is that we don’t focus on troubleshooting information enough. And you see these sites like Stack Overflow and other social channels where the main focus is on troubleshooting information, solving specific problems and addressing error messages they’re seeing.

He said that with minimalism, a third of the content should really be focused on troubleshooting. I think part of this reason why we often don’t add more troubleshooting information is because of this disconnect with users. If we were more like aware of all these problems, we’d probably shift our focus more to this troubleshooting area. Anyway …

All right, so now you have some questions for me, too, that you want to ask, so why don’t we shift gears a little bit and now you drive questions and all I’ll answer?

 

Nupoor: Great, I’d like to continue from the previous question, what I asked practitioners, and also ask you too. Can you talk about what you do on a day to day basis as the technical or professional communicator with the organization that you’re part of?

 

Tom: I work at Amazon in the Appstore side of the business, which is not AWS. Most people just kind of assume that I work in AWS and it’s not the case. There are hundreds of technical writers at Amazon. Only like a third of them are AWS. Anyway, the Appstore is focused on getting third-party developers to build apps for Amazon’s platforms, like Fire TV, Fire tablet, and other services.

So my main effort is to try to get people to create apps. The audience is people who are often seasoned developers, but not necessarily, so it could include everybody from those who create well-known apps to somebody who’s creating an app you’ve never heard of. I work with various engineering teams and they push out features.

In my current group, we’re a two person team in terms of the tech writers. We plug into developer marketing and developer relations. So we have people who are performing business analysis roles, people who are performing developer marketing roles, and even, like Salesforce techs and so forth in our group.

Because we’re only two, two people, we will often work with a lot of different teams within the organization. Sometimes we write the docs for these teams, but other times we’ll just say, hey, you need to submit a pull request (or code review, CR) with the changes you want into the documentation, because we’re not going to write it. We don’t know your product, and we’re not going to ramp up on it, but we are going to edit and publish your documentation. That’s becoming more common as the organization grows and it just becomes impossible to write for all these different teams. As a result, we end up becoming more like the gatekeepers and managers and content stewards of the content. This role has its pluses and minuses.

 

Nupoor: Yeah, I an see that with the gatekeeper manager role. I’m sure you also have to do a lot of editing and reviewing each other’s work since you are the only two writers there. Do you have an editorial team for that kind of work?

 

Tom: There’s another doc team that has an editor and they’ve got a style guide, and they’re a little bit more robust in terms of their size. I think they have, you know, five times as many writers as our team (or they once did). So yeah, it just varies. There’s lots of like different pockets of writers at Amazon. Some are more robust than others.

If you’re part of AWS, then you’re part of a group of more than a hundred writers. And if you’re part of Seller Central, you’re also part of a big group. But you could also be a lone writer, and as such maybe you’ll have to come up with all your own tools, your own delivery method, whereas if you’re part of a big group, you’re, you’re aligning with that group’s existing toolset and workflow.

 

Nupoor: That’s great. So do you use the docs-as-code approach?

 

Tom: Yes, we do. And now here’s where I do want to expand a little bit. To provide some background on docs-as-code, because this is new concept for many academics and others, the basic philosophy is to treat documentation somewhat the same as you treat code.

Not exactly of course, but you write in markdown, typically using an editor such as Visual Studio C. You manage the content in Git, usually. You don’t perform all the builds locally. You just push your update updates to a server and the server kicks off the build and deploys the content.

Because you’re writing in a simple format like Markdown, o reStructuredText or ASCII doc or something, users can easily contribute. Whereas in the past, if you were writing in XML, it’s much more daunting because XML is more complex. XML is not something you can just pick up in a minute or two.

So do we follow docs as code? Yes. And there there are varying degrees that people can follow docs as code. I mean, you don’t necessarily have to check all the boxes. The reason people would want to consider docs as code is not just because it’s kinda neat to use similar software methodologies for docs as developers, but rather the whole premise of docs as code is to unlock collaboration with developers and meet them and their tool space so that they can more easily contribute and collaborate with documentation.

As such, it really only makes sense to use docs as code if you’re trying to collaborate with developers. In the organization I’m in, I mentioned we’re two technical writers working with a lot of different teams, so if we want these other teams to contribute an author content, it won’t work if we ask them to write in XML. In contrast, if we tell them, hey, all you have to do is write in Markdown and you’re going submit a pull request, just like you do with your code, following a similar process as with your software code, then they they are much more open to contributing.

Methodologies and practices vary of course. In my group, the term we use is to “raise a CR,” which means to initiate a code review that others can approve. After approval, the CR gets merged in with the master code. This approach makes sense when you want engineers to write and contribute more to documentation (though this also has its pros and cons).

One advantage of docs as code is that people don’t need special tools or proprietary licenses. You can change their content after you merge it in, or you can reject the pull request and require them to fix a few things first. You can say, no, this isn’t good enough to merge in. Or you need more detail, so work on it more. And people sort of understand that workflow, you don’t have to explain it. They get it. And that’s kind of a cool approach. But again, only for developers and only in basically software documentation shops that are creating dev docs such as API docs. If you’re in other industries, I don’t think it makes as much sense.

 

Nupoor: You were talking about the format of the documents and that because it’s Markdown, it’s easier to merge in their pull requests. So I’m assuming that you’re using GitHub for the infrastructure?

 

Tom: We’re using Git. We’re not, not necessarily GitHub. Github is just an online hub that manages Git projects. Most companies have their own internal Git infrastructure. We’re just piggybacking off of that at our company for docs. I recently did some surveys asking people what their tools are, and it’s very common that people have custom tools. By custom it’s likely their company’s infrastructure, engineering build management systems and so forth. That’s pretty much the default now. Developers manage their code using Git within their company’s own infrastructure. We’re just leveraging that. If you have developers helping to build out our own doc workflows, it will be easier to use the same infrastructure and tooling. It just makes it easier.

 

Nupoor: But …

 

Tom: Sorry, I wanted to add one more thing. I have tried actually putting content out on GitHub, and I know that AWS group does do this, or rather, one of their outputs is GitHub, interestingly enough. GitHub is probably important to consider if you’re trying to get users, not just internal engineers and stakeholders, to author and contribute to the content. If you want to actually get the user’s feedback, GitHub can be important because it gives them a place to log issues and otherwise interact. Whereas if you don’t have that, that distribution point, it makes it very difficult.

But having all your source on GitHub is not easy because when you’re creating content prior to release, you can’t really push it out there on GitHub because a GitHub is open. So you have more complexities in terms of how you’re going to manage that content. Anyway….

 

Nupoor: Yeah, no, I think that’s a great point. And I can understand how this could work best for like a smaller team, a team where you have developers contributing content such as API docs in your case. But like you said, being open puts a lot of pressure on the project management process itself in some ways. There are many people participate in constantly other release cycles and tend to doing all of that.

 

Tom: When you say too many people participating, do you mean like internal, internal engineer’s authoring or external users?

 

Nupoor: I mean external users creating issues and constantly the documentation being updated in some way or the other.

 

Tom: Yeah, one unfortunate reality is that once you release a product, you kind of move on to another, same with the development team. Teams aren’t allocated and resourced to projects for the entire life of the project. You’re not always available and dedicated to that project. So let’s say you create a sample app, you push it out to GitHub, and at first it’s exciting. You know, people are are downloading it, they’re cloning your project, they’re forking it. But then the engineering team moves on. The tech writer moves on because that project is sort of done, but users keep logging issues on GitHub. They have suddenly a public space where they can note problems, right?

And you don’t want to look like you’re ignoring them. So you want to address them, but suddenly you don’t have the bandwidth anymore, because that’s no longer your active project. This puts companies in a difficult position. So it’s kinda like, if you’re going to put content on GitHub, theoretically you should manage that content for as long as it’s on GitHub. But now you have this uncomfortable problem that you may have to reject requests for fixes. Maybe there’s a bug and that’s just how it’s going to be. Or maybe people want more information about something and you don’t have the bandwidth to create another tutorial or enhancement to the doc anyway.

That’s kind of the realities of having a lot of different projects and a lot of different teams that are constantly changing and shifting. But we are sort of empowering users by putting content on GitHub. It’s kind of like on amazon.com when you buy a product and suddenly you can review the product, right? If you don’t like it, you, you have a public space on the retail site where you talk about all its problems. Well on GitHub, if you’ve got an issues log where people are like noting all kinds of problems, that’s a good thing if you’re trying to make it better, right, if you want to actually improve it.

But it can be a bad thing if you’re like, uh, we’re kind of archiving this project in a read-only mode. GitHub empowers people with a voice. But you might only want that input if you’re actively working on the project, trying to make it better. This is usually a best practice. There’s no way you can anticipate all the problems people will have with things, before it’s released. But on the other hand, writers and dev teams aren’t always working in this mode to actively improve products, and when this happens, the public space for users to interact can be difficult, especially if you’re a customer-centric company.

 

Nupoor: Yeah, that’s really interesting. Considering the lifetime of the project, it’s such an important thing as they move to collecting user feedback. I’m trying to understand how the writer’s responsibilities have changed, changed, over the period of time, either for using the docs as code approach or for content that is otherwise openly authored, where anyone can come in and contribute. I’m interested in how writers are now acting more as collaborators, as reviewers, moderators, gatekeepers, like you mentioned earlier. Could you, tell us a little more about each of these goals.

 

Tom: Yes, I do think the role is significantly changing, especially in, in the developer documentation domain. A lot of times the technologies are complex, right? They’re often things that like the engineers themselves just need to document and explain. I mean, technical writers can, of course, write all this content, and there are varying levels of tech savvy, but the ability to, to jump in and suddenly explain it all, like o, here’s how you’re gonna make all your calls with this C++ API, and here’s the workflow, etc., it’s not practical to quickly document all of this. You want to let developers explain the code that they’ve written. At the same time, developers often don’t have much of a clue about publishing tools or how to get content in front of users. So technical writers will often play more of an editorial and publishing role.

It’s also important to note that the tech writer facilitates the review of content, which is something that that shouldn’t be sort of minimized. When a developer writes something, the technical writer says, okay, great, now let’s review this content with the field engineers. Let’s review this content with the support team and we’ll see if they present any issues.

As a technical writer, you’re kind of pulling together different parts of the organization around content to review and improve it. In contrast, if engineers are just writing and they don’t have that review process and mechanism, they probably won’t go out of their way to pull in other groups, e.g., Legal, or maybe a different project manager who’s also affected by the code.

I hate to generalize about engineers, but it’s sort of impossible in this situation. Engineers tend to be myopic and focused on a specific sliver of what they’re doing because they’re specialized people. They have have deep knowledge about what they’re doing, but not necessarily broad knowledge across the organization about all the different stakeholders that need to be looped in.

So the tech writer plays an important role in bringing together all these different groups around the content. Then once you publish the docs, you also facilitate the voice of the user in the reception and adoption of the content too. Your role involves presenting the user’s voice and relaying their feedback and experience to those internal engineering teams.

Engineering teams tend to be somewhat removed and isolated from user groups. This is by design, so that they’re not constantly getting a barrage of user input and feedback and requests. As such, that insulation can make them unaware of users’ feedback. At the same time, engineering teams are very hungry to understand how users are using the product, what their feedback is.

And so the technical writer can also play this role where you champion the user’s voice, and you present their feedback and you say, hey, you know, our field engineers say that is a problem they’re having. Or maybe on GitHub, these are the issues people are logging or, or you can say, hey, traffic-wise, nobody’s hitting this page.

Or everybody’s going to page X and we have no idea why — is there some issue there? So you bring the users and their input back into the internal workings of the organization. That’s an interesting shift. You may not be writing the content, right? You may just be editing it, publishing it, facilitating review and presenting the user feedback.

All those activities are incredibly important because they influence the content, but they don’t necessarily require you to author the content. That said, it’s not as if you can be completely unaware of what the content is all about, right? If there’s a workflow that describes something, you have to understand whether the right language is being used, the right terms and lingo, whether it’s aligning with sort of industry best practices and so forth. But a lot of that will come out when you begin this review process.

 

Nupoor: That’s really interesting to me. It seems like it’s a very genre specific, so it works for the product documentation and, and bigger, or like maybe smaller organizations, but more of in a software company, where the focus is on content publishing and involves different teams. I’m also wondering about those beginning in technical writing, maybe trying to do a certification course or a master’s degree in technical communication and who wants to apply for a job like this. Do you think that that’s a skill, the collaboration aspect, is that a skill that you look for when you’re hiring technically writers for your team?

 

Tom: This is another sad kind of aspect of the profession — there’s a disconnect between the hiring criteria and what people actually do on the job. Hiring criteria basically requires, at least in the API doc space, requires candidates to be tech savvy. A lot of companies, especially if they have engineers who are running the hiring committee will favor tech, and if a candidate can’t articulate a code sample in the way they want, then they may get passed over. I don’t think that when people hire, they’re aware of all of these other roles technical writers can play. These roles such as editor, publisher, a collaborator reviewer, they’re often overlooked.

People don’t realize these other roles that a writers play. To give some credit, you do have to have a technical foundation to work with content, right? And to be able to learn what you need to learn to understand the right language and workflows. But I think it’s overemphasized and good candidates might get overlooked.

So you really have to be able to sell yourself. You have to be able to articulate the value that you bring. Different companies have different hiring processes, granted, but in addition to tech depth, writing skills be required. You’ll have to submit writing samples that show that you have like a good command of the language, that you can organize things well, that you can express complex concepts clearly.

And then a third sort of facet is your leadership skills, like how well do you interact with engineers? Because, you know, the process I’ve been describing is that you’re interfacing with a lot of different people, right? So you’ve got to have good people skills, and you’ve got to sort of demonstrate people skills.

In an interview your interviewer might ask about a time you pushed back against a trend that people wanted to go. And how did you sort of negotiate that conflict, you know. If you can’t really speak to it, well then they may conclude that you wouldn’t be a good fit.

So it’s not just a matter of giving lip service to having people skills. It’s being able to dig up experiences that demonstrate how you mediated conflict and kind of moved forward an idea, or a how you dug deeper to find customer data to promote a certain direction that you wanted to go. Trying to find candidates that check all these boxes with leadership and writing skills and tech skills is challenging.

And then when they get in the role, you’ll realize that you have multi-dimensional role as an editor and a publisher and a collaborator and a reviewer. There’s a lot of different facets of tech comm, and they might be emphasized in different scenarios and teams.

 

Nupoor: Yeah, that is interesting. I really liked the idea of presenting yourself as a user advocate, which I think students can do in their own spaces, when they are working on their graduate studies or when they are working on projects by themselves or open source authoring and trying to contribute to these open source software and documentation.

I mean, that could be a good place to start for them. And then to showcase their skills and the ability to play these different roles. So I think those were all the questions that I had.

 

Tom: Hey, I just have one more question. This was one I had on my list for you, but I didn’t ask earlier. So you’re focusing a lot on having the user be a producer of knowledge or looking at ways users influence the production of knowledge.

I’m just kinda wondering how these concepts might apply in academia. Let’s say that PhD candidates are writing dissertations. How could you have the audience for the dissertation also be part producer in that dissertation? Is that something that’s ever been done or like, is that not feasible and why?

 

Nupoor: Incidentally, because I’ve chosen this project, or this idea for my dissertation, I decided to write my dissertation on GitHub. And NC state has their own enterprise version of GitHub. So right now I have hosted the first chapter on GitHub, which I can open up to collaborators or other researchers who would want to contribute to it. But because dissertation as a genre which is focused on a single student and their own work throughout their PhD, there might be privacy concerns.

But let’s say it was a research paper that people wanted to co-author. That’s a methodology that has been extensively used these days, which is called the collaborative auto-ethnography, where people from different places bring in experiences about a certain concept and write a paper together, and then kind of bring out themes from it and start documenting them.

That’s a method which for a journal paper, and it could work, using an open operating platform like GitHub. So how I see it happen is that, every research project including dissertations has a literature review, for example. And people always come across different literature. So far for me alone, like my literature review chapter is probably going to be about 20 to 30 pages.

There is only so much literature that I myself can dive into and come up with and start writing or documenting. But if I had help from other researchers who themselves have done similar research and they want to contribute their ideas, doing it would be a more comprehensive chapter or a more comprehensive depiction off the research and the certain field, that is doable through GitHub.

Now the flip side. Some challenges would be authoring in a certain format, understanding tools and the technology and publishing information. Right now I’m using Visual Studio Code and publishing with LateX to generate out a PDF. That’s the infrastructure limitation that people might face. Instead, if I were writing in Markdown and publishing on GitHub, or using an easier method of writing, like Microsoft word or Google doc, then it would be totally accessible for people to contribute in it.

So I think it could work. Just like I think it’s good work for technical manuals. The other day I was listening to that was posted on your blog. It’s by Ralph Squillace it’s on open authoring collaboration across the disciplines. I think it’s a recording of Ralph’s presentation that you have posted.

The idea of open source documentation where a lot of people contribute, but only 5% of that content is really helpful. But then in order to generate that 5%, we need so many more resources, which are so hard to find. I am bringing that reference just to explain this more clearly, the kind of value that collaboration can add to any project, based on if they understand the genre, the context, and the purpose of, of writing it.

 

Tom: Well, I think that’s great. I’m sort of blown away by the mere fact that you’re managing your dissertation in a project on GitHub. Now you’ve suddenly made everything open, right? Now we can see the progress, assuming it’s a open GitHub project, we can see kind of the directions you’re taking. We can make notes. I could go in and log an issue and maybe say, Hey, consider this or add this research. I think that’s awesome.

This reminds me, there’s is a project that Ann Gentle has with collecting docs as code case studies or samples. She has this whole book on docs like code and she tries to find different people who have implemented docs like code who want to share their experiences. She lets people submit them as case studies.

It’s hard to collaborate on a single piece of writing, but if you have a lot of different experiences that people can write up and contribute, I think that that works too.

What kind of input can I channel your way from practitioners? e.g., surveys? Are you trying to gather more contact points for people who want to share their experiences, or is there any other way that I can help you, gather practitioner input for your data collection?

 

Nupoor: I would like to hear from practitioners who are working in software companies and who used the open docs as code approach or the open authoring approach, in which they collect feedback from users in some way. That’s what I would like to know. Sometimes the feedback is more visible, especially with processes such as users creating or logging issues, writing feedback about the documentation, etc. Other times the audience influence is less visible, such as when writers collect user data from channels such as Google Analytics or any other kinds of data analytics too.

And if they’re doing any of these things, then I would really like to talk to them and understand the ways in which they are writing and publishing documentation. So that would be great help.

 

Tom: I can definitely round up some people. I recently realized that having a popular blog gives me visibility with people. When I did my recent developer document trends survey, I just embedded this little note at the top of every post, and gathered around 400 responses. So I would be more than happy to put a little note there saying, Hey, if you are gathering data from users who want to participate in this survey/research, reach out to Nupoor. How many people are you looking to get? Do you want to have 20 people or 200 people?

 

Nupoor: I’m looking for 15 to 20 people. Okay.

 

Tom: Okay, cool. Yes, I mean, I’m trying to facilitate sort of a bridge between industry and academic collaboration points, just because I feel like I have that opportunity. And if we could get you the right data, that would be great because I would personally be very interested to see the different approaches people have, what are people doing to leverage all this user feedback to influence, the knowledge produced and so on.

Nupoor, thank you so much for being on his podcast. I enjoyed it. And, enjoyed hearing about your research and I hope this project goes well. Any last words or thoughts that you want to share? Like how maybe how people can find you or where they can learn more about you?

 

Nupoor: Sure, thanks Tom for having me and I’m really excited to share the idea on your blog and hear how people are contributing. I can be reached through email at [email protected]. Also, my Twitter handle is @nupoorwriting. Thanks so much for having me.

 

Tom: Thank you.

More reading

To read more of my thoughts on this topic, see this follow-up post, Are technical writers increasingly playing non-technical roles? Some thoughts on the evolution of technical writing roles.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.

© 2024 Tom Johnson