Moving into API documentation writing
-
Upload
ellis-pratt -
Category
Technology
-
view
357 -
download
3
Transcript of Moving into API documentation writing
![Page 1: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/1.jpg)
Moving into API
documentation writing
Ellis Pratt @ellispratt
![Page 2: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/2.jpg)
About meDirector at Cherryleaf, a technical writing services and training company in the UK
(with an API training course)
![Page 3: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/3.jpg)
About you
Who creates API documentation today?
![Page 4: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/4.jpg)
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
![Page 5: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/5.jpg)
1.What is an API?
![Page 6: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/6.jpg)
A way for applications to exchange information
![Page 7: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/7.jpg)
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
![Page 8: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/8.jpg)
Behind the scenes
APIApp
Developer API Team
Request
![Page 9: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/9.jpg)
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
![Page 10: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/10.jpg)
APIs types you’ll probably see
REST APIs
Native library APIs (for Java, C++, .NET etc)
![Page 11: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/11.jpg)
http protocols
Users make requests for the resources on a Web server.
The server returns responses containing the information.
APIhttp request ->
<- http response
![Page 12: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/12.jpg)
http protocols
API
PythonApp
JavaScriptApp
RubyApp
![Page 13: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/13.jpg)
Components of a REST API
![Page 14: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/14.jpg)
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
![Page 15: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/15.jpg)
Example - Your NHS number
The API might state it wants the NHS number in:
numerical (9434765919)
or
alphanumerical string (“943-476-5919”)
format.
![Page 16: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/16.jpg)
Resources
APIAppRequest
These are the “information objects” the API can exchange
Resources have data associated with them (e.g. the patients’ names)
![Page 17: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/17.jpg)
Endpoints
APIAppRequest
http://ABC-hospital.nhs/patients/
A http address where you can find a resource
![Page 18: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/18.jpg)
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)
![Page 19: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/19.jpg)
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"
![Page 20: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/20.jpg)
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
![Page 21: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/21.jpg)
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.
![Page 22: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/22.jpg)
2.APIs and the role of documentation
![Page 23: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/23.jpg)
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
![Page 24: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/24.jpg)
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.
![Page 25: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/25.jpg)
What else?
![Page 26: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/26.jpg)
Explain what it does
What it does
The overall process
Any underlying concepts
![Page 27: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/27.jpg)
Signing up for an account
Signing up for an account
Getting API authorisation keys
![Page 28: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/28.jpg)
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
![Page 29: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/29.jpg)
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.
![Page 30: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/30.jpg)
Tutorials
For different programming languages
To get to “Hello World”
![Page 31: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/31.jpg)
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
![Page 32: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/32.jpg)
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
![Page 33: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/33.jpg)
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.
![Page 34: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/34.jpg)
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.
![Page 35: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/35.jpg)
3.The role of an API documentation writer
![Page 36: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/36.jpg)
Technical Author
Task-based content
To a less technical audience
What Technical Authors do
![Page 37: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/37.jpg)
What Technical Authors do
Technical Author
Filter content for different audiences
Publish to different media
Re-use content
Localise
![Page 38: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/38.jpg)
API Writer
Reference-based content*
To a technical audience
Single use document
English only
What API doc writers do
* Mostly
![Page 39: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/39.jpg)
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
![Page 40: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/40.jpg)
4.The skills you need
![Page 41: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/41.jpg)
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
![Page 42: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/42.jpg)
5.The tools
![Page 43: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/43.jpg)
API tools for documentation
![Page 44: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/44.jpg)
Developers may be writing
Comments in code
The documentation
Using their own tools
![Page 45: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/45.jpg)
API doc writers’ tools
Less sophisticated
Built to suit the developers’ workflow
Low cost, open source
Simple markup
![Page 46: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/46.jpg)
Improving the tools
It’s getting there
Lightweight DITA may help
![Page 47: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/47.jpg)
5.Becoming an API documentation writer
![Page 48: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/48.jpg)
The grass is greener?
Lots of software developer are currently working on APIs
![Page 49: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/49.jpg)
Let’s look at some vacancies
On reed.co.uk from mid-February 2016……
![Page 50: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/50.jpg)
![Page 51: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/51.jpg)
![Page 52: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/52.jpg)
Search carried out on 15/2/2016
Of the 5,000 UK Technical Authors
on LinkedIn
173 included “API” in their
profile
![Page 53: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/53.jpg)
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
![Page 54: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/54.jpg)
A lot of recruitment is by word of mouth
Following entrepreneurs as they more from business to business
![Page 55: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/55.jpg)
Improve skills
You can get by with a wide and shallow understanding of programming
![Page 56: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/56.jpg)
Improve skills
Learn Python basics
Understand what the tools can do
Assist on open source projects
More training courses are emerging
![Page 57: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/57.jpg)
Summary
![Page 58: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/58.jpg)
What are the takeaways?
It’s a growing area
It’s changing rapidly
It requires more technical skills
It’s well paid
![Page 59: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/59.jpg)
Questions
![Page 61: Moving into API documentation writing](https://reader030.fdocuments.us/reader030/viewer/2022013123/58e4d64b1a28abf5048b5513/html5/thumbnails/61.jpg)
End
© Cherryleaf 2016
Images and screenshots © their respective owners