Generalist versus specialist: What should you focus on with knowledge building in your tech writing role?
Background
In small companies, or even in large companies when I’m allocated to a small number of engineers (like 10-20), my role has involved writing most of the documentation for a project. But at my current company, there are many more engineers, with more specializations and diverse product needs.
Additionally, sometimes the content is more technical than I can author myself. For example, to publish an in-depth tutorial in using the audio APIs in Android as they relate to streaming media apps, complete with code samples an even sample apps, I really need the expertise of an engineer who intimately knows the APIs, best practices, and Android code as gathered from real-life experience developing apps.
While I could ramp up on this tech and author the content, it would take me a while. It’s easier to get the media-focused engineer to contribute this knowledge, which I then edit, attempt to test (if possible), and then publish.
In a way, duplicating the engineer’s deep technical knowledge is somewhat inefficient, because now multiple people possess similar knowledge, while other knowledge areas get neglected. For example, the documentation toolset and workflow could potentially suffer. Same with the documentation’s information architecture, search, and discoverability.
Contributing in other ways
If I don’t specialize my knowledge in the product’s tech, how should I focus my knowledge building and time as a technical writer? What value would I bring to the table as a technical writer without deep technical knowledge of the product? Here are a few value areas outside of the deep technical knowledge:
- I can see the larger picture of the documentation and integrate the information holistically where it fits, adjusting other topics and making the whole doc coherent and seamless. (I wrote about this in Updating a single page versus updating the documentation as a whole.)
- I can build doc publishing tools that maximize the user experience by providing navigation, search, tags, and other good UX features for users. (Most engineers know very little about documentation websites or publishing.)
- I can solicit the information we need, commit engineers to write, and push the content through the appropriate approval channels. (In short, I would be a kind of producer on a movie set, directing actors and scenes for the desired result.)
- I can analyze user feedback from forums, support logs, search queries, metrics, websites, and other channels. Based on my analysis, I could take action to either solicit the needed content, adjust the existing content, or provide more strategic direction about any gaps.
- I can organize authoring workflows with git and repos to allow engineers to write and collaborate, submit pull requests, and push out new content somewhat autonomously. Orchestrating this distributed git workflow for doc can help us scale our efforts across the company.
- I can analyze the information architecture of the doc site, how various products are organized, how users navigate to them, and provide the right tags and facets to increase findability across the documentation.
I can do all of the above, but often I don’t simply because I’m focused on creating yet another new documentation article or topic by somewhat replicating the engineer’s technical knowledge (a portion of it anyway). Writing is hard work, and I can easily spend the full day just creating one new doc article.
Rather than burying my head in the technical details of Android APIs and how to build streaming media apps, I might instead spend more time becoming an expert in areas such as the following:
- Authoring tools
- Search tools
- Product industry knowledge
- Knowledge of users
- Collaborative git workflows
- Metrics
Which is the better approach?
Time is not infinite
Although it’s easy to say that tech writers should be technical SMEs and doc ninjas at the same time, in reality one has only so much time.
I can’t be a specialist in everything. If I want to build up my Android knowledge, it means doing a worse job with some of the above doc tasks. Conversely, if I spend time digging into doc metrics, information architecture, and search optimization, it means spending less time building my deep technical knowledge (such as with Android and Java).
I do think it’s important to have a basic knowledge of the technical foundation of the product, including familiarity with the right terms and basic functions. But my knowledge is always going to be superficial compared to an engineer’s.
Should I therefore focus my time developing expertise in the unique features of my tech writer role as listed in the points above? Engineers can supply the deep technical knowledge, but they seem to fall short doing all the other documentation functions. Am I being inefficient by trying to write when I should really just pull this information from engineers in the first place?
The flip side
On the other hand, without deep technical knowledge, it’s almost impossible to write coherently and intelligently about the product.
Many of the doc infrastructure tools, once in place, can fit seamlessly and invisibly into the background. It’s this deeper technical knowledge that empowers me as a writer to shape the actual content in meaningful ways. Content development is surely one of the most important aspects of documentation, because users care primarily about content.
Conclusion
Overall, it can be overwhelming to consider all the types of knowledge a tech writer needs to be successful.
I only have about 2 hrs a day max to soak in new technical knowledge. Sometimes it’s more important to be an expert in the doc/publishing tools and workflows, while other times it’s important to have deeper technical knowledge, and other times it’s important to build up knowledge of users and their interactions.
The problem is that by spreading my time in so many different directions, I dilute my expertise and become a generalist, with a little knowledge of lots of different things.
Being a generalist might be the defining characteristic of technical writing. I often want to be a specialist, but specializing usually entails blocking out other areas that also need my attention.
This dilemma over being a generalist versus a specialist seems to be a recurring theme in my tech writing career that I’ve never been able to resolve.
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.