TCUK16 presentation

1. Moving into
API
documentation
writing
Ellis Pratt
@ellispratt

2. About me
Director at Cherryleaf, a technical writing
services and training company in the UK
(with an API training course)

3. About you
Who creates API documentation today?

4. Overview
1. 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

5. 1.What is an API?

6. A way for applications to
exchange information

7. 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

8. Behind the scenes
API
App
Developer API Team
Request

9. What developers do with
APIs
API
App
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

10. APIs types you’ll probably
see
REST APIs
Native library APIs (for Java,
C++, .NET etc)

11. http protocols
Users make requests for the
resources on a Web server.
The server returns responses
containing the information.
API
http request ->
<- http response

12. http protocols
API
Python
App
JavaScript
App
Ruby
App

13. Components of a
REST API

14. 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

15. Example - Your NHS number
The API might state it wants
the NHS number in:
numerical (9434765919)
or
alphanumerical string
(“943-476-5919”)
format.

16. Resources
API
App
Request
These are the “information objects” the API can exchange
Resources have data associated with them (e.g. the patients’ names)

17. Endpoints
API
App
Request
http://ABC-hospital.nhs/patients/
A http address where you can find a resource

18. API Rules
A 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)

19. 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"

20. 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

21. 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.

22. 2.APIs and the role of
documentation

23. 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

24. 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.

25. What else?

26. Explain what it does
What it does
The overall process
Any underlying concepts

27. Signing up for an account
Signing up for an account
Getting API authorisation keys

28. 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

29. 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.

30. Tutorials
For different programming
languages
To get to “Hello World”

31. 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

32. 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

33. 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.

34. 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.

35. 3.The role of an API
documentation writer

36. Technical Author
Task-based content
To a less technical audience
What Technical Authors do

37. What Technical Authors do
Technical Author
Filter content for different
audiences
Publish to different media
Re-use content
Localise

38. API Writer
Reference-based content*
To a technical audience
Single use document
English only
What API doc writers do
* Mostly

39. 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

40. 4.The skills you need

41. Skills required
Technical 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

42. 5.The tools

43. API tools for documentation

44. Developers may be writing
Comments in code
The documentation
Using their own tools

45. API doc writers’ tools
Less sophisticated
Built to suit the developers’
workflow
Low cost, open source
Simple markup

46. Improving the tools
It’s getting there
Lightweight DITA may help

47. 5.Becoming an API
documentation writer

48. The grass is greener?
Lots of software developer are
currently working on APIs

49. Let’s look at some vacancies
On reed.co.uk from mid-
February 2016……

52. Search carried out on 15/2/2016
Of the 5,000 UK
Technical Authors
on LinkedIn
173
included “API” in their
profile

53. 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

54. A lot of recruitment is by
word of mouth
Following entrepreneurs as
they more from business to
business

55. Improve skills
You can get by with a wide
and shallow understanding of
programming

56. Improve skills
Learn Python basics
Understand what the tools
can do
Assist on open source
projects
More training courses are
emerging

57. Summary

58. What are the takeaways?
It’s a growing area
It’s changing rapidly
It requires more
technical skills
It’s well paid

59. Questions

60. For more information
ellis@cherryleaf.com
@ellispratt

61. End
© Cherryleaf 2016
Images and screenshots ©
their respective owners