API: Value of Documenting Software Interactions

Have you ever come to realize how interconnected things are in the computer world today? There are dozens of operating systems and piles of applications out there, and their number grows each day at the speed of light. And the greater that number becomes, the more the need for interactivity gets.

Why would we care about software interactions? Well, imagine yourself having a night out with a gang of your pals. And suddenly you all decide to go to the movie tomorrow. The legend says that our ancestors in such cases were concerned about coming to the cinema two hours earlier, staying in line at the box office, and quite often still getting unlucky to run short of tickets available or, at the best case, get the aisle seats of the last row.

Today, we simply open a cinema app on our devices the moment we come up with the idea and become few swipes and a couple of taps away from getting the tickets purchased without even having to print them.

This is called the almighty API in full play.

What is API

So what is API? Let me dig a bit deeper into the cinema tickets case. Once the brilliant idea to go see a movie pops up in your mind – you open the application on your, say, iOS device and tap your way through to the stage of selecting a seat for a particular reel of film, and then tap the final OK button.

After your move, the application sends your input data (or request) to the server where all logs regarding tickets, seats, movie halls as well as booking, purchasing, and any other customer’s activity are stored and kept up to date.

The received data is processed on the server and the corresponding records are logged in. As a result, the return data (or response) is sent to your application in the form of, let’s say, notification that your purchase has been confirmed, and the bar code appears on your display as an alternative to old-school paper tickets.

This is just one of thousands of examples of API operational behavior. Nowadays, API is crucial for majority of software units – applications, servers, programs, operating systems, etc. Think of API as connection means that helps us get linked to each other and the rest of the world like never before.

What is API documentation

In the sphere of technical communication, there is a large branch assigned to API documentation that occupies a special place in the software developers’ world.

Basically, API documentation covers the description of the code: the request sent to particular software, the description of the processes executed by the software, and the responses received. Documenting API includes description of functions, parameters, variables, and class structures – all well-organized with supplementary notes when needed.

As an example of API documentation, below is provided the description of a basic and quite simple request to reset password for a user’s account in a web-based application.

ChangePassword

POST/ChangePassword

Description

This request is used to change password for a user’s account while the user is logged in.

Input Parameters

The ChangePassword method accepts the following parameters.

Name	Type	Description
password	string	User’s old password.
newPassword	string	User’s new password. A new password must contain at least ten characters, among them must be at least three numeric characters and at least one uppercase character.
newPassword2	string	Confirmation of the new password.

Return Parameters

If the new password input is valid, the success response is sent.

The example above does not include the description of cases if any invalid data has been input. If so, the response would contain multiple lines indicating that the new password validation is false and displaying the corresponding error message why the input data has not been accepted and the request failed to be successfully processed.

Why document API

Unless there is the only one developer who will use and contribute to the API they have developed, their brainchild needs to be carefully documented for the following reasons:

• For someone who visits the API for the first time, most likely, it will be a black box. Therefore, to cease the pain caused by excruciating procedure of dealing with the code and easily learn the interface of a computer program, the API documentation would be a lifesaver.
• In terms of internal API used within a project development team, a Project Manager can sleep tight at nights knowing that if the key developers decide to leave the team some day, there won’t be any troubles for newcomers to get acquainted with the interface and resume working with the API from whatever point needed.
• Decent API documentation of a multifunctional and truly handy program ensures its distinctness and availability for other programs and services to connect and, therefore, promote its usage within wider audience.

For instance, the most frequently used external APIs (available for anyone to use) are the ones that belong to Facebook, Google Maps, Twitter, and YouTube. This means that these sharks of the software market are widely referenced and communicated by other apps, platforms, and devices. Take Facebook, for example: throughout the years, it has become a reliable login service, a perfect advertising platform, and a gaming solution as well. This is one of the bright examples of social media API in use.

Another example of the eternal cross-platform development possibilities is the Find Facebook Friends option available on the Home page in Skype. This rather convenient feature allows using one’s Facebook account to expand the list of contacts in Skype.

Producing the developers-focused documentation is of a true value to a technical communicator in terms of knowledge-acquiring aspect.

Mastering programmer’s documentation, APIs in particular, requires from a technical communicator solid technical background. Since API documentation can be produced for many kinds of technologies, for example XML or JSON schemas, C++, C#, Java, and more, profound skills at reading source code is an indispensable requirement to a writer.

At some companies, it is not enough to simply read and document code. It might also be required to be able to review the code produced by developers or even write your code samples, which indisputably widens your personal area of technical knowledge.

However, not only your technical background and striving to accomplish the best results assure successfully documented API, but so does human factor! Effective communication with the API developers, who should be just as much interested in comprehensive API documentation as you are, is another, I’d say, crucial key to your outstanding results.

Producing API documentation is surely beneficial for a technical communicator these days from the financial aspect as well.

If to consider salary-related matter, documenting APIs, SDKs, and other programmer’s documentation is generally paid more than producing user-oriented documentation. According to the statistics provided by one US-based employment web agency, the latest graphs based on the collected data, which were compiled in October 2015, demonstrate that the average technical writer yearly salary in the USA is 53.000 USD. Senior technical writer’s yearly income is 67.000 USD, while API technical writer (no level mentioned) receives around 72.000 USD per year.

Conclusions

It is not a simple task for a technical communicator to develop API documentation, particularly, if some specific technical background knowledge is missing. But who said it’d be easy, huh?

What can be claimed though, is that it is rather a challenging piece of work whose effective completion depends directly on the author’s attentiveness to details, complete understanding of source code, thorough analysis and profound research abilities.

And eventually, you will be granted great appreciation and gratitude from those developers who will deal with the API, bringing up that desired feeling of a small professional victory each of us strives to attain.