This guest blog post was written by Dr. David Marshall, a technical writer and a training developer since 2007. He is also the owner of Neithdos Consulting Services LLC. Dr. Marshall received his DM in Executive Leadership from Colorado Technical University in 2021.
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. An SDK software may also include the source code for that specific platform to allow developers to modify the code and suit it to their needs. For example, the Android SDK provides developers with a set of necessary tools and resources for building applications specifically for the Android operating system. This includes access to APIs and libraries, as well as the source code for the Android platform itself.
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 software 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 software 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 when it comes to software and app development. 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. It also includes technical support resources to resolve more complex issues 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.
MadCap Flare is a powerful technical writing software that can greatly simplify the process of writing and maintaining your SDK documentation. With Flare, you can create and publish documentation in multiple formats, including HTML5, PDF, and mobile-friendly formats. Flare provides a range of authoring and collaboration features that can help you streamline your documentation process, such as version control, conditional text, and topic-based authoring. Additionally, Flare's responsive design and localization features can help ensure that your documentation is accessible and useful to developers around the world. By using MadCap Flare, you can save time and resources while ensuring that your SDK documentation is of the highest quality.
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/
