Aye, Aye, API - What makes Technical Communicators uneasy about API documentation, and what can we do about it?
•
7 gostaram•1,860 visualizações
Presentation at the GDS' and Write The Docs London's Documenting APIs - all day mini-conference
Recomendados
Recomendados
Mais conteúdo relacionado
Mais procurados
Mais procurados (20)
Semelhante a Aye, Aye, API - What makes Technical Communicators uneasy about API documentation, and what can we do about it?
Semelhante a Aye, Aye, API - What makes Technical Communicators uneasy about API documentation, and what can we do about it? (20)
Mais de Ellis Pratt
Mais de Ellis Pratt (13)
Último
Último (20)
Aye, Aye, API - What makes Technical Communicators uneasy about API documentation, and what can we do about it?
- 1. Aye, Aye, API What makes Technical Communicators uneasy about API documentation and what can we do about it? Ellis Pratt
- 2. Overview 1. The role 2. The skills required 3. The tools 4. What can we do about it? Image: Tim Peake
- 3. About me Director at Cherryleaf, a technical writing services company
- 4. 1. The role
- 5. Technical Author Task-based content Technical stuff to a non-technical audience What Technical Authors do
- 6. What Technical Authors do Technical Author Filter content for different audiences Publish to different media Re-use content Localise
- 7. API Writer Reference-based content* Technical stuff to a technical audience Single use document English only What API doc writers do * Mostly
- 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. 2. The skills required
- 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. 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. Recruiting via mainstream recruitment agencies They want to match key words in the job description to a candidate’s CV
- 13. Let’s look at some vacancies Three adverts for API Technical Authors/Writers on reed.co.uk from mid- February 2016……
- 14. 1.
- 15. 2.
- 16. 3.
- 17. Search carried out on 15/2/2016 Of the 5,000 UK Technical Authors on LinkedIn 173 included “API” in their profile
- 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. 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. 3. The tools
- 22. Technical Authors’ tools Complex tools for complex problems Built to suit the needs of the organisation Structured authoring Versioning Multilingual
- 23. API tools for documentation
- 24. API doc writers’ tools Less sophisticated Built to suit the developers’ workflow Low cost, open source Simple markup
- 25. Perception of API tools for documentation
- 26. Perception of API tools for documentation Unfamiliar Flat file CMS Often require CSS skills
- 27. Perception of API tools for documentation Can be difficult to install Poor documentation Limited support
- 28. The tools can do more than you think
- 29. Variables
- 32. Conditional text (sort of)
- 33. Add review comments and track changes
- 34. Link validation (but link management can be problematic)
- 35. Versioning
- 36. What happens when someone falls under a bus? But API doc systems are often bespoke
- 37. Hopefully we’ll see more work on Standardisation Localisation (Welsh) Conditional text Structured content Link management Image:Tom Johnson
- 38. Help Authoring tools can do more than you think
- 40. Automatic builds
- 41. Source control/Binding to Git
- 42. HTML5 frameless responsive web look and feel
- 43. What Help authoring tools can do Print outputs Filter content Collaborative authoring
- 44. Hopefully we’ll see more work on Exporting to Markdown Round-tripping Markdown
- 45. 4. What can we do about it?
- 47. Improve skills More training courses are emerging More studying Share ideas And understand what the tools can do
- 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. 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. 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. Run doc sprints
- 53. Docs are a team responsibility Share the same issue tracker Share the same review tool?
- 55. Improve the tools It’s getting there Lightweight DITA may help Images can be an issue
- 56. Make it easy for developers to write Set standards Provide guidelines Provide templates Enable them to use their own tools
- 57. Be the content strategist “Gather it Organise it Share it It’s what you’re good at” Sarah Maddox, Technical Writer, Google
- 58. Learn from each other TCUK 2016
- 59. Summary
- 60. What are the takeaways? Don’t seek a unicorn Don’t abdicate responsibility The tools are improving Authors - improve your skills
- 61. Questions
- 63. End © Cherryleaf 2016 Images and screenshots © their respective owners