Writing Agile

Iterative_development_model.svg

If you’ve documented software over the last five years, you’ve no doubt heard a bit (or a lot) about “Agile” software development. (If not, this Wikipedia page will get you started.) In contrast to more traditional models of development that emphasize sticking to a set plan and following a linear process until the entire project is completed, Agile favors iterative development and regular re-evaluation of the product to assess whether it’s successfully meeting its requirements.

Continue reading

When Is Writing Not Enough?

Written by Michael Benavidez

Michael

I’ve participated in a wide variety of technical writing courses, seminars, and presentations as a way to break into the industry. The speakers I’ve heard come from diverse backgrounds and experiences, but one common subject is that of change. Technical writer jobs today are not the same as they were ten or even five years ago. New skills are needed.

One of the technical writing instructors in my certificate program, a man who had worked on projects at companies such as Microsoft and Disney, talked about the importance of adding one or more skills to our writing credentials. He had been a technical writer and editor for many years, but decided to learn programming after realizing his skills alone wouldn’t be enough as the work evolved.

There can be varying skills technical writers need to have in order to perform their job, depending on the industry. Two employers might list very different qualifications for similar positions.

While pursuing my technical writing certificate, I’ve started to learn how to code. I don’t expect to become a programmer any time soon, but I think this skill will help me speak the language and write more accurate documentation.

Unquestionably, becoming familiar with different areas of technical writing is as important as having writing skills.

 

What is API Documentation?

Written by Peter Gruenbaum

API documentation is a fast-growing segment of technical writing. API stands for Application Programming Interface, and it’s the way that software systems communicate with each other. What sets it apart from other types of documentation is that you are writing for an audience of software developers. APIs provide certain functionality, and software developers need to understand how the APIs work in order to build applications that use them.

There are several types of APIs, including programming APIs, web APIs, and hardware APIs. This article will discuss the two most common types, which are programming and web APIs.

Do you need to know how to write code in order to document APIs? There isn’t a simple answer to that question. For some types of APIs, you should know programming fairly well. For other types, it may not be required, but it is often useful.

Programming APIs

A programming API (also called a “client library” or SDK, for Software Development Kit) is a set of software functionality that runs on a device, such as a smartphone, tablet, desktop, or server. For example, a software developer creating an iPhone app would use the iOS SDK. Let’s say that a developer wanted to be able to pop up a window that asked a question and prompted the user to tap “OK” or “Cancel”. API documentation tells the developer what code is required to do that action. It may involve several steps, such as first creating the dialog, then displaying it, and then reacting to the choice that the user made. The developer needs to know how to specify the message, how to specify what buttons to display, and how to find out what button the user tapped.

API documentation writers definitely need to understand some level of programming in order to document programming APIs, but how much you need to know will vary. The documentation for the iOS example I gave above (UIAlertController) requires a great deal of knowledge about iOS programming in order to understand it. However, many programming APIs are a lot simpler, and require only that you have a good understanding of object-oriented programming languages like Java. If you write documentation without having that solid understanding, then you may write something that is not completely accurate, and developers will no longer trust the documentation.

Web APIs

A web API defines the communication between a client device and a server over the web. Web APIs are a relatively new phenomenon in the software industry, but several recent technology trends (mobile devices, the internet of things, and big data) have made them extremely popular. The site ProgrammableWeb contains a directory of publicly-available web APIs, and they analyze the data and look for trends. As you can see in the graph below, the number of these APIs have grown exponentially. And these are just the public APIs — people in the industry say that there are 10 times more web APIs that are available only internally or to partners.

Source: ProgrammableWeb

Source: ProgrammableWeb

 

There is a debate in the API documentation community as to whether writers need to know how to program in order to document web APIs. Understanding programming can give you a good perspective on how web APIs are used. That said, web APIs are not really about programming as much as they are about data. The most important thing you need to understand to document web APIs is how to document structured data, such as XML (eXtensible Markup Language) and JSON (JavaScript Object Notation).

What API Documentation Should Cover

Like any kind of technical writing, API documentation needs to provide both overview material to orient the reader, and reference material to provide specific information on how to accomplish tasks. Here are sections that are common in API documentation:

• Overview — what the API does and why you should use it
• Getting Started — a short series of steps to quickly get to the first use of the API
• Architecture — for programming APIs, how the various pieces fit together
• Authentication — for web APIs, how security is handled
• Tutorials — step-by-step instructions that leads the reader through how to accomplish common tasks
• Reference — detailed information on what each piece of the API does

How to Learn More

Several resources are available to learn more about API documentation. They include:

STC webinars by Sarah Maddox, Ed Marshall, Joe Malin, and others

Workshops by Marshall Documentation Consulting

Online courses by SDK Bridge