moving into api documentation writing

Moving into API

documentation writing

Ellis Pratt @ellispratt

About meDirector at Cherryleaf, a technical writing services and training company in the UK

(with an API training course)

About you

Who creates API documentation today?

Overview1. What is an API?

2. APIs and the role of documentation

3. The role of an API documentation writer

4. The skills you need

5. The tools

6. Becoming an API documentation writer

Image: Tim Peake

1.What is an API?

A way for applications to exchange information

Lots of websites use information from APIs

Find a GP near to your postcode

Information is requested from the NHS Choices API and displayed on the web page

www.whereilive.norfolk.gov.uk

Behind the scenes

APIApp

Developer API Team

Request

What developers do with APIs

APIApp

Developer

Developers write code to take the data provided in the response and use it in their applications (“parsing”)

There is code in the Web page to request data and then

display the data on a map

NHS application containing list of GP practices in a

database

APIs types you’ll probably see

REST APIs

Native library APIs (for Java, C++, .NET etc)

http protocols

Users make requests for the resources on a Web server.

The server returns responses containing the information.

APIhttp request ->

<- http response

http protocols

API

PythonApp

JavaScriptApp

RubyApp

Components of a REST API

A hospital API

An API will consist of a set of rules describing how an application can interact with it

and

the mechanisms that allow such interaction to happen.

API

Example - Your NHS number

The API might state it wants the NHS number in:

numerical (9434765919)

or

alphanumerical string (“943-476-5919”)

format.

Resources

APIAppRequest

These are the “information objects” the API can exchange

Resources have data associated with them (e.g. the patients’ names)

Endpoints

APIAppRequest

http://ABC-hospital.nhs/patients/

A http address where you can find a resource

API RulesA hospital API will consist of a set of rules describing how an application can interact with it (specifically, a resource):

Create/Add information (Post)

Request information (Get)

Update information (Put/Patch)

Delete information (Delete)

(and run an application)

Requests to an API

Get me Jane Brown’s records

Get me a list of all the patients leaving hospital today

Get me the Consultant’s name who is attached to Mrs Brown

etc

GET http://ABC-hospital.nhs/patient/JaneBrown

curl --get -k --include "http://ABC-hospital.nhs/patient/?name=jane brown&NHS=9434765900" -H "X-Key: ABC12345" -H "Accept: text/plain

curl -X GET -H "Cache-Control: no-cache" -H "Postman-Token: 97bb9ba5-f763-208e-b9e4-5d7bd3861835" "https://fhir-open-api-dstu2.smarthealthit.org/Patient/1551992"

How do the API team create APIs?

They may use an API Specification

They may make REST calls in the programming language they are using

API

API Team

They may use a type of API Specification

API Specification tools can generate the code for REST calls in a programming language.

Programmers can then add this code to their application.

2.APIs and the role of documentation

What content goes into an API document?

Content Buzzword

A clear definition of what resource it represents Resource description

The accepted input Parameters, Request submission example

The produced output Request response example

Links (where can you go to find what exactly) Endpoints

Automatically generated content

When you describe your API using the Swagger or RAML specification, some tools can read those specifications will generate an interactive documentation output.

What else?

Explain what it does

What it does

The overall process

Any underlying concepts

Signing up for an account

Signing up for an account

Getting API authorisation keys

The 3-30-3 goal

The 3-30-3 goal

3 seconds - what it does

30 seconds - why you should use it

3 minutes - to do something

TTFHW - Time to first "Hello World"

A simple exercise

How quickly you can get an application to output “Hello World”?

For APIs it might be how to construct a request and receive a valid response.

Tutorials

For different programming languages

To get to “Hello World”

Why do we need code samples?

REST APIs aren’t tied to a specific programming language

So developers may need advice on how to submit HTTP requests in their particular programming language

Creating code samples

Some API providers decide to provide one code sample (usually in cURL) and let the developer extrapolate the format in his or her own programming language.

curl --get -k --include "http://ABC-hospital.nhs/patient/?name=jane brown&NHS=9434765900" -H "X-Key: ABC12345" -H "Accept: text/plain

Creating code samples

Others want to encourage developers to use their API, and want to make it as easy as possible by providing code samples.

Creating code samples - Don’t panic!

In some cases, developers supply the code samples

You briefly add comments to the code samples.

The patterns for making REST requests in different programming languages follow a common template.

3.The role of an API documentation writer

Technical Author

Task-based content

To a less technical audience

What Technical Authors do

What Technical Authors do

Technical Author

Filter content for different audiences

Publish to different media

Re-use content

Localise

API Writer

Reference-based content*

To a technical audience

Single use document

English only

What API doc writers do

* Mostly

There are some differences

Technical Author API Writer

Task-based content Reference-based content

To a non-technical audience To a technical audience

Re-use content Single use

Localise English only

4.The skills you need

Skills requiredTechnical Author API Writer

1 Writing skills Coding sample writing skills

2 Time management skills Domain knowledge

3 Tools skills Tools skills

4 Domain knowledge Time management skills

5 Writing skills

5.The tools

API tools for documentation

Developers may be writing

Comments in code

The documentation

Using their own tools

API doc writers’ tools

Less sophisticated

Built to suit the developers’ workflow

Low cost, open source

Simple markup

Improving the tools

It’s getting there

Lightweight DITA may help

5.Becoming an API documentation writer

The grass is greener?

Lots of software developer are currently working on APIs

Let’s look at some vacancies

On reed.co.uk from mid-February 2016……

Search carried out on 15/2/2016

Of the 5,000 UK Technical Authors

on LinkedIn

173 included “API” in their

profile

Finding a unicorn“Finding a technical writer who commands

a high degree of English language fluency

in addition to possessing a deep technical knowledge of Java, Python, C++, .NET, Ruby, and more

is like finding a unicorn.”Tom Johnson

Flickr image: Owlana

A lot of recruitment is by word of mouth

Following entrepreneurs as they more from business to business

Improve skills

You can get by with a wide and shallow understanding of programming

Improve skills

Learn Python basics

Understand what the tools can do

Assist on open source projects

More training courses are emerging

Summary

What are the takeaways?

It’s a growing area

It’s changing rapidly

It requires more technical skills

It’s well paid

Questions

For more information

ellis@cherryleaf.com

@ellispratt

End

© Cherryleaf 2016

Images and screenshots © their respective owners