If you were recruiting for a technical writer to document Algolia, how would you word the job requirements? Can you now see why even though the core work involves documenting the REST API, it would also be good to have an “ability to read code in one or more programming languages, such as Java, C++, or Python.”
The number of SDKs a company distributes can vary considerably. You might not have six SDKs in multiple languages and frameworks for your API. You might be in a C++ only shop where all you need to know is C++ and nothing more. If that’s the case, you’ll need to develop a deeper knowledge of C++ so you can provide more value in your writing role.
Although the proliferation of code and platforms creates pressure on the multi-lingual capabilities of technical writers, if you can understand what’s going on in one programming language, your description of the reference implementations in other programming languages will follow highly similar patterns.
What mainly changes across languages are the code snippets and some of the terms. You might refer to “functions” instead of “classes,” and so on. Even so, getting all the language right can be a challenge, which is why it’s so hard to find technical writers who have skills for producing developer documentation, especially for the SDKs and sample apps.
Providing value without in-depth technical knowledge
The degree to which you can provide value in your role as a technical writer is often directly proportional to your level of technical knowledge. For example, if you land (or inherit) a job that involves working with several API projects involving languages you don’t know, you can still facilitate the documentation for the projects. However, you’ll play more of an editing/publishing role rather than an authoring role.
In many highly technical shops, this editor/publisher role is becoming increasingly common. Engineers will write the technical material, especially the reference documentation, and technical writers will focus more on making sure the content checks all the boxes — that it has an overview, release notes, addresses user tasks, follows the style guide, integrates with the other docs, and so on. You can shape and organize the content, and identify areas where it’s deficient or needs expansion, but the ability to add deeper value requires a deeper knowledge of the subject matter.
A lack of more technical knowledge will likely remove some of the value from your role. In How API Documentation Fails, Martin Robillard and Gias Uddin explain:
Perhaps unsurprisingly, the biggest problems with API documentation were also the ones requiring the most technical expertise to solve. Completing, clarifying, and correcting documentation require deep, authoritative knowledge of the API’s implementation. This makes accomplishing these tasks difficult for non-developers or recent contributors to a project.
Without in-depth, authoritative knowledge of the API, it will be challenging to complete, clarify, and correct errors in the content.
' //Acrolinx contents[1]='' //Xpublisher contents[2]='
Explore Xpublisher, the workflow-based CMS for technical communication
The balance between generalist and specialist roles is an ongoing challenge that I’ll explore more in the next topic: How much code do you need to know? In short, if you want to solve the biggest problem with API documentation, you’ll need to develop more technical expertise in the subject domain.
Consolations for technical writers
As a consolation to this stress of having to navigate multiple programming domains, you can take comfort in the fact that REST APIs (which remember are language agnostic) are becoming more common and are replacing native-library APIs. The advantages of providing a universally accessible API using any language platform usually outweigh the specifics you get from a native library API.
For example, when I worked at 41st Parameter (a startup acquired by Experian), the company had a Java, .NET, and C++ API — each implementation did the same thing but in different languages. We also had an SDK for Android and iOS.
Maintaining the same functionality across three separate API platforms was a serious challenge for the company’s developers. Not only was it difficult to find skill sets for developers across these three platforms, having multiple code bases made it harder to test and maintain the code. It was three times the amount of work, not to mention three times the amount of documentation.
Additionally, since native library APIs are implemented locally in the developer’s code, it was almost impossible to get users to upgrade to the latest version of the API. We had to send out new library files and explain how to upgrade versions, licenses, and other deployment code. If you’ve ever tried to get a big company with a lengthy deployment process on board with making updates every couple of months to the code they’ve deployed, you realize how impractical it is. Rolling out a simple update could take 6-12 months or more. During that time, the company is often struggling with a load of bugs and other issues that are setting them back.
It’s much more feasible for API development shops to move to a SaaS model using REST, and then create various client implementations that briefly demonstrate how to call the REST API using the different languages. With a REST API, you can update it at any time (hopefully maintaining backward compatibility), and developers can continue using their same deployment code.
As such, you won’t be hopelessly lost if you can’t navigate these other domains in the programming languages. Your core function will hopefully involve documenting the REST API, with brief docs on the client SDKs mostly authored by the engineers.
That said, one area where REST APIs can be problematic is with devices (for example, smartphones and tablets, devices in cars, streaming media devices). In these cases, calls to REST APIs tend to be slow, so a native library API (such as Android) is used instead.
In the next topic, How much code do you need to know?, I’ll explore the topic of how much code you need to know and strategies for learning it.
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.
115% Complete
115/177 pages complete. Only 62 more pages to go.
« Previous: Chapter 12: Thriving in the API doc space
© 2023 Tom Johnson
I'm Tom Johnson, an API technical writer based in the Seattle area with a demonstrated expertise in technical writing, software documentation, and API documentation. I have a comprehensive understanding of the challenges faced by technical writers, particularly in the realm of API documentation. My knowledge is grounded in practical experiences and a deep engagement with the nuances of technical communication.
In the context of recruiting a technical writer for documenting Algolia, the job requirements should reflect a balance between generalist and specialist roles. While the core responsibility involves documenting the REST API, it's crucial to emphasize the need for the candidate to possess an "ability to read code in one or more programming languages, such as Java, C++, or Python." This requirement is based on the understanding that even in a scenario where a company might primarily use a single language, having a broader comprehension enhances the writer's ability to add value.
I concur with the article's assertion that the proliferation of code and platforms necessitates technical writers to be adept in multiple programming languages. Although the code snippets and some terms may vary, the underlying patterns remain similar. A technical writer's capability to understand one programming language facilitates the translation of that understanding into consistent and accurate documentation across different languages.
The article rightly highlights the growing trend of technical writers taking on more of an editing/publishing role in highly technical environments, where engineers often handle the authoring of reference documentation. However, it emphasizes that the depth of technical knowledge correlates with the level of value a technical writer can provide. Without a profound understanding of the API, addressing issues and enhancing documentation becomes challenging.
Moreover, the article references the difficulties outlined by Martin Robillard and Gias Uddin in "How API Documentation Fails," emphasizing that solving intricate documentation problems requires a high level of technical expertise. It suggests that a lack of in-depth knowledge could hinder the ability to complete, clarify, and correct errors in the content.
The discussion on the balance between generalist and specialist roles in technical writing resonates with the challenges posed by the evolving landscape of API documentation. The article provides valuable insights into the changing role of technical writers, where a deeper understanding of the subject matter is becoming increasingly essential.
In conclusion, the overarching theme is clear: technical writers in the API documentation space need to continually enhance their technical expertise to meet the demands of evolving technologies and diverse programming languages. The article sets the stage for a deeper exploration of the question: How much code do you need to know? This ongoing exploration is crucial for technical writers aiming to thrive in the dynamic API documentation space.
