The terms API and SDK are often used together, but they are not synonymous. SDKs implement a language-independent REST API in a specific language, such as Java or C ++. REST APIs themselves are not tied to any particular language; we typically demonstrate APIs by making requests using cURL, a command-line tool for sending web requests and receiving responses. But developers won’t use cURL queries when implementing an API. Instead, they will implement API requests using the language in which their application is written.
For example, Python, C++, or Node applications implement API requests in different ways. Each language has its own way of constructing API requests. You can use Postman or Paw to automatically generate a simple request in a particular language. SDKs take implementation to another level. SDKs can include many more files or libraries as part of the implementation.
What is the technical writer’s role in documenting SDKs and sample applications
In the SwaggerHub guide, we learned how to automatically generate client SDKs in the SwaggerHub interface. Typically, if your development team proposes a client SDK, instead of an automatically generated SDK, there will be code that the development team prepares and tests. The development team often provides the SDK in multiple target languages depending on their user’s primary language, making it easier for users to implement the API.
For a technical writer of APIs, documenting SDKs and sample applications is a more difficult task, because SDKs require knowledge of one or more programming languages. The question of how much code a technical writer needs to know will be discussed in the Technical Writer Job module, so we won’t go into detail here. Usually developers don’t expect you to have a deep knowledge of several programming languages, but some understanding will be required to describe them and review documentation. When deciding whether to call a block of code a function, class, method, or other name, you need to have a basic understanding of the terms used in the language.
If the language is unfamiliar, you can just take what engineers write, clean it up a bit, try going through the steps to get any sample applications working, and see what feedback comes from users. Usually, if you can install and work with a sample app and make sure that the basic documentation for running the app works and what the app does, that might be enough. But of course, making any significant contribution to the SDK documentation will require knowledge of the programming language in which the SDK is written.