Who can make documentation requests
The scenario
Consider this scenario. Your DevRel group is working with a partner and notices that the lack of a tutorial for some feature Product X is causing friction. So the DevRel engineer goes to your doc intake form and files a request for a Product X tutorial for the feature. Sounds good because DevRel teams are closely focused on partner needs, right? And this would allow you to create more user-focused docs.
Well, when the request for a Product X tutorial lands in your technical writing lap, you have to start chasing down contacts and information in ways that might be really frustrating. Who owns Product X? Or more specifically, who is the SME for the requested feature related to Product X? And once you track down the right person, how willing/available will this person be to help a technical writer? Chances are, not much if the request involves more than one meeting.
In contrast, if you ask DevRel teams to make requests for documentation through the product teams, this accomplishes two things:
- It identifies the owner for the information. You no longer have to play guessing games about where to go to find the info. The team making the request will often allocate an engineer to provide the needed info for docs.
- The product team ponies up some bandwidth to work with you on the documentation, often by creating a draft or supplying other info.
This week was particularly frustrating for me because I wasn’t following this workflow. I was working through partner-facing groups but unable to get much traction on a requested ticket. Everywhere I turned, I seemed to run into a deadend. Then I observed how another team bent over backwards delivering information for a partner-facing request, and it dawned on my what my error was. I shouldn’t have allowed the DevRel group to file the ticket themselves, but rather should have instructed them to pressure the product team who owns the feature to file the doc request.
Based on this experience, I added a section in my API course title Requests should come through product teams.
Larger lesson
The larger lesson here relates to intake processes. Intake processes are at the heart of the tech comm workflow. Here’s a secret: Almost no one understands what your team’s tech comm processes are initially because few people work with tech writing teams, and most teams have different processes. There are no standards. How does one request documentation, and then how does that documentation request play out? It’s a guessing game because it varies so much from team to team.
The trick to being a more efficient technical writer is to put more of the documentation pain onto the requester than the requestee (i.e.., the technical writer). If you allow someone to make vague requests for documentation, this puts information pain on technical writers to gather a host of details about what needs to be updated, who has the information, who needs to review the information, what the update consists of, and so on.
This is why your intake form should be as specific as possible. For example, see these two sections for more elaboration on sample intake questions/fields:
The more information you can gather from requesters, the better positioned you’ll be to take action in an efficient way.
It’s very easy, however, for tickets to clog up a backlog. And while I would need to more carefully analyze this, my guess is that many tickets that don’t get acted on are tickets that aren’t actionable because of the reasons I described here – the source of information is fuzzy, unclear. The person who owns the doc related to the feature is unclear, etc.
About 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.