Posted December 24, 2024

In a previous blog “Types of Technical Writing” there was a discussion of the different types of documentation including case studies, end-user guides, proposals, brochures, online articles, and white papers just to name a few. In this blog, we are going to discuss a specific type of technical documentation that is used for creating software applications, Software Development Kit Documentation.  However, the first thing that we are going to discuss is What is SDK?

What is SDK?

Imagine bringing your favorite pet to the veterinarian clinic for a routine checkup. Upon entering the clinic, the receptionist takes a picture of your pet using a pet recognition software application.

Once the receptionist takes a picture of your pet, the app communicates with the visual recognition server on the cloud. In turn, the visual recognition server downloads the pet’s information including its name and all other pertinent information to the receptionist. The Software Development Kit contained in the pet recognition software applications uses code to tell the App to get the pet’s information.

Software Development Kit or SDK is a set of tools, libraries, relevant documents, code samples, processes and/or guides that allow developers to create software applications on a specific platform. These applications will then be able to communicate with other software applications to perform a function.

Purpose of SDK

The purpose of SDK is to avoid reusing code so that the development team can concentrate on creative work. SDK provides all of the necessary code that a user will need to build an application that uses API.

Benefits of SDK

SDK is beneficial because it writes common code that can be used over and over so that developers can concentrate on other things besides worrying about common code. SDK also helps the user start work with the software applications quickly and easily. This is done by testing the code during the initial setup to ensure functionality.  Other benefits of SDK include:

• Launching new projects more quickly
• Reliability
• Little to no mistakes
• Comprehensive documentation on how the code works
• Easy to use by developers
• Works well with other SDKs
• Provides functionality to add value to other software apps
• Quick integration
• Scalable
• Secure

Now that we understand what an SDK is, let us go over how to document the SDK process.

SDK Documentation

SDK documentation is a set of supporting documents that helps the end user and overall user experience with the software application. The documentation is vital because it explains how an SDK works on a particular operating system such as Google or iOS or with a specific programming language such as Java or Python.

Role of the Technical Writer in SDK Documentation

Technical writers need to have input on developing SDK documentation. However, it can be a challenge. It is important for writers when it comes to creating SDK documentation that they are familiar with one or more programming languages. The writer will also need to know how the product works in order to avoid using the wrong technological terms or not understanding the process.

If the writer is not that familiar with the programming language, terms, and processes, they will need to work with the engineers and developers who are apart part of the development process. Getting involved with the development process helps the technical writer get acquainted with the product and become familiar with the right terminology.

This will help create valuable documentation. After the document has been completed, it is essential to have the developers review the material to ensure accuracy. Another way is to have an engineer and/or a developer write the SDK documentation. Most likely it will be in either engineer or developer jargon. This is where the writer will come in and make updates so that the end user will be able to read and understand.

Parts of SDK Documentation

There are a number of key sections of SDK documentation. To include a few: How-to-guides, release notes, readme files, troubleshooting documentation, and use cases.

How-to-Guides

How-to-Guides include implementation guidelines that explain how to incorporate the SDK into the project. The guide will also include explanations about how to perform tasks that involve the SDK.

Release Notes

Release notes are technical documents that contain bug fixes and added features. This information is for end users, customers, and clients of the organization that created the SDK.

Readme Files

A README file contains information about the software. Below is a list of the items that can be in a README file:

• An Overview of the SDK functionality
• Links to the SDK documentation
• Links to Tutorials
• Point of Contact for Support
• Release Notes
• Version Details

Troubleshooting Documentation

Troubleshooting documentation provides information on how to solve problems with the application and how to prevent reoccurring issues.

Use Cases

Use cases provide practical examples and how the SDK is relevant in real-world situations. These cases will highlight the essential functions of the application.

Examples of SDK Documentation

There are many software applications that use SDK documentation such as Windows, Apple, and RedHat. Below are a few examples of applications that we all use daily that have SDK documentation:

PayPal REST SDK

The PayPal SDK includes a Wiki page, source docs, sample code, API reference, and SDK releases.

Amazon SDK

The Amazon SDK has various document generators for the programming languages.

Google Cloud

The tutorial is an overview of all of the APIs in SDK (gcloud, gsutil, and ba). It also provides step-by-step instructions on installing the latest version of the Google Cloud SDK. It also provides quick start guides for the different operating systems.

Authoring Tools

Using the authoring tool is much easier to create SDK documentation. The authoring tools improve the look of the documentation and enhance teamwork. One of the tools that is out there for creating SDK documentation is ClickHelp. ClickHelp presents fragments of code or code examples in an easy-to-read format also known as the syntax highlighter.

ClickHelp separates the code fragments from regular text using a different color. The editor helps produce SDK documentation that looks as close as possible to the web page.

Summary

Writing SDK documentation can be challenging but it also can be rewarding. The reason it can be challenging is that the writer needs to be familiar with the software, programming language, and jargon.

It can be rewarding because the writer is able to interact with the developers and engineers who create the application and get involved with the development process.

References

SDK Documentation: What is it and what is the difference between SDK and API? By Elmira – March 9, 2022, https://clickhelp.com/clickhelp-technical-writing-blog/sdk-documentation-what-is-it-and-what-is-the-difference-between-sdk-and-api/

SDKs (software development kits) by I’d Rather Be Writing - November 17, 2019, https://idratherbewriting.com/learnapidoc/docapis_sdks.html

Managing SDK Releases by I’d Rather Be Writing - August 17, 2020, https://idratherbewriting.com/learnapidoc/docapis_managing_sdk_releases.html

Types of Technical Writing by Anastasia – March 4, 2021, https://clickhelp.com/clickhelp-technical-writing-blog/types-of-technical-documentation/

What is an SDK? Software Development Kits Explained by OKTA – June 30, 2022,https://www.okta.com/identity-101/what-is-an-sdk/