Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Moving into API documentation writing

967 views

Published on

TCUK16 presentation

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Moving into API documentation writing

  1. 1. Moving into API documentation writing Ellis Pratt @ellispratt
  2. 2. About me Director at Cherryleaf, a technical writing services and training company in the UK (with an API training course)
  3. 3. About you Who creates API documentation today?
  4. 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. 5. 1.What is an API?
  6. 6. A way for applications to exchange information
  7. 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. 8. Behind the scenes API App Developer API Team Request
  9. 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. 10. APIs types you’ll probably see REST APIs Native library APIs (for Java, C++, .NET etc)
  11. 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. 12. http protocols API Python App JavaScript App Ruby App
  13. 13. Components of a REST API
  14. 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. 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. 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. 17. Endpoints API App Request http://ABC-hospital.nhs/patients/ A http address where you can find a resource
  18. 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. 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. 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. 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. 22. 2.APIs and the role of documentation
  23. 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. 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. 25. What else?
  26. 26. Explain what it does What it does The overall process Any underlying concepts
  27. 27. Signing up for an account Signing up for an account Getting API authorisation keys
  28. 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. 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. 30. Tutorials For different programming languages To get to “Hello World”
  31. 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. 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. 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. 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. 35. 3.The role of an API documentation writer
  36. 36. Technical Author Task-based content To a less technical audience What Technical Authors do
  37. 37. What Technical Authors do Technical Author Filter content for different audiences Publish to different media Re-use content Localise
  38. 38. API Writer Reference-based content* To a technical audience Single use document English only What API doc writers do * Mostly
  39. 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. 40. 4.The skills you need
  41. 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. 42. 5.The tools
  43. 43. API tools for documentation
  44. 44. Developers may be writing Comments in code The documentation Using their own tools
  45. 45. API doc writers’ tools Less sophisticated Built to suit the developers’ workflow Low cost, open source Simple markup
  46. 46. Improving the tools It’s getting there Lightweight DITA may help
  47. 47. 5.Becoming an API documentation writer
  48. 48. The grass is greener? Lots of software developer are currently working on APIs
  49. 49. Let’s look at some vacancies On reed.co.uk from mid- February 2016……
  50. 50. Search carried out on 15/2/2016 Of the 5,000 UK Technical Authors on LinkedIn 173 included “API” in their profile
  51. 51. 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
  52. 52. A lot of recruitment is by word of mouth Following entrepreneurs as they more from business to business
  53. 53. Improve skills You can get by with a wide and shallow understanding of programming
  54. 54. Improve skills Learn Python basics Understand what the tools can do Assist on open source projects More training courses are emerging
  55. 55. Summary
  56. 56. What are the takeaways? It’s a growing area It’s changing rapidly It requires more technical skills It’s well paid
  57. 57. Questions
  58. 58. For more information ellis@cherryleaf.com @ellispratt
  59. 59. End © Cherryleaf 2016 Images and screenshots © their respective owners

×