moving into api documentation writing
TRANSCRIPT
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
End
© Cherryleaf 2016
Images and screenshots © their respective owners