Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.

Aye, Aye, API - What makes Technical Communicators uneasy about API documentation, and what can we do about it?

Presentation at the GDS' and Write The Docs London's Documenting APIs - all day mini-conference

Aye, Aye, API - What makes Technical Communicators uneasy about API documentation, and what can we do about it?

  1. 1. Aye, Aye, API What makes Technical Communicators uneasy about API documentation and what can we do about it? Ellis Pratt
  2. 2. Overview 1. The role 2. The skills required 3. The tools 4. What can we do about it? Image: Tim Peake
  3. 3. About me Director at Cherryleaf, a technical writing services company
  4. 4. 1. The role
  5. 5. Technical Author Task-based content Technical stuff to a non-technical audience What Technical Authors do
  6. 6. What Technical Authors do Technical Author Filter content for different audiences Publish to different media Re-use content Localise
  7. 7. API Writer Reference-based content* Technical stuff to a technical audience Single use document English only What API doc writers do * Mostly
  8. 8. 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
  9. 9. 2. The skills required
  10. 10. Skills required Technical Author API Writer 1 Writing skills Domain knowledge 2 Time management skills Tools skills 3 Tools skills Time management skills 4 Domain knowledge Writing skills (code sample writing skills)
  11. 11. Skills required -Take 2 Technical Author API Writer 1 Writing skills Coding skills? 2 Time management skills Domain knowledge 3 Tools skills Tools skills 4 Domain knowledge Time management skills 5 Writing skills (code sample writing skills)
  12. 12. Recruiting via mainstream recruitment agencies They want to match key words in the job description to a candidate’s CV
  13. 13. Let’s look at some vacancies Three adverts for API Technical Authors/Writers on reed.co.uk from mid- February 2016……
  14. 14. 1.
  15. 15. 2.
  16. 16. 3.
  17. 17. Search carried out on 15/2/2016 Of the 5,000 UK Technical Authors on LinkedIn 173 included “API” in their profile
  18. 18. 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
  19. 19. Not an easy problem to solve Especially someone with 5+ year’s REST API writing experience In the USA, rates are 1.5 to 2 times that of non-API jobs The work can be seen as boring
  20. 20. 3. The tools
  21. 21. Help authoring tools
  22. 22. Technical Authors’ tools Complex tools for complex problems Built to suit the needs of the organisation Structured authoring Versioning Multilingual
  23. 23. API tools for documentation
  24. 24. API doc writers’ tools Less sophisticated Built to suit the developers’ workflow Low cost, open source Simple markup
  25. 25. Perception of API tools for documentation
  26. 26. Perception of API tools for documentation Unfamiliar Flat file CMS Often require CSS skills
  27. 27. Perception of API tools for documentation Can be difficult to install Poor documentation Limited support
  28. 28. The tools can do more than you think
  29. 29. Variables
  30. 30. Single source content
  31. 31. Multi-channel publishing
  32. 32. Conditional text (sort of)
  33. 33. Add review comments and track changes
  34. 34. Link validation (but link management can be problematic)
  35. 35. Versioning
  36. 36. What happens when someone falls under a bus? But API doc systems are often bespoke
  37. 37. Hopefully we’ll see more work on Standardisation Localisation (Welsh) Conditional text Structured content Link management Image:Tom Johnson
  38. 38. Help Authoring tools can do more than you think
  39. 39. Colour coded syntax
  40. 40. Automatic builds
  41. 41. Source control/Binding to Git
  42. 42. HTML5 frameless responsive web look and feel
  43. 43. What Help authoring tools can do Print outputs Filter content Collaborative authoring
  44. 44. Hopefully we’ll see more work on Exporting to Markdown Round-tripping Markdown
  45. 45. 4. What can we do about it?
  46. 46. 4.1 Recruitment/Skills
  47. 47. Improve skills More training courses are emerging More studying Share ideas And understand what the tools can do
  48. 48. Understand the developers’ tools
  49. 49. Set realistic expectations You are more likely to find someone with a wide and shallow understanding of programming Look for writers who can read code, rather than write it
  50. 50. Set realistic expectations Developers should not abdicate responsibility Developers may need to create the code examples Have clear requirements Don’t ask the author to invent something that takes the best from other API documentation sites Image: Simon Greig
  51. 51. Docs are a team responsibility You should be one team Docs should be part of the definition of Done Docs should be part of the review process Image: St Helens RFC
  52. 52. Run doc sprints
  53. 53. Docs are a team responsibility Share the same issue tracker Share the same review tool?
  54. 54. 4.2 Tools/Standards
  55. 55. Improve the tools It’s getting there Lightweight DITA may help Images can be an issue
  56. 56. Make it easy for developers to write Set standards Provide guidelines Provide templates Enable them to use their own tools
  57. 57. Be the content strategist “Gather it Organise it Share it It’s what you’re good at” Sarah Maddox, Technical Writer, Google
  58. 58. Learn from each other TCUK 2016
  59. 59. Summary
  60. 60. What are the takeaways? Don’t seek a unicorn Don’t abdicate responsibility The tools are improving Authors - improve your skills
  61. 61. Questions
  62. 62. For more information ellis@cherryleaf.com @ellispratt
  63. 63. End © Cherryleaf 2016 Images and screenshots © their respective owners

×