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.
Aye, Aye, API
What makes
Technical
Communicators
uneasy about API
documentation and
what can we do
about it?
Ellis Pratt
Overview
1. The role
2. The skills required
3. The tools
4. What can we do about it?
Image: Tim Peake
About me
Director at Cherryleaf, a technical writing
services company
1. The role
Technical Author
Task-based content
Technical stuff to a non-technical
audience
What Technical Authors do
What Technical Authors do
Technical Author
Filter content for different
audiences
Publish to different media
Re-use conten...
API Writer
Reference-based content*
Technical stuff to a technical
audience
Single use document
English only
What API doc ...
There are some differences
Technical Author API Writer
Task-based content Reference-based content
To a non-technical audie...
2. The skills required
Skills required
Technical Author API Writer
1 Writing skills Domain knowledge
2 Time management skills Tools skills
3 Tool...
Skills required -Take 2
Technical Author API Writer
1 Writing skills Coding skills?
2 Time management skills Domain knowle...
Recruiting via mainstream
recruitment agencies
They want to match key words
in the job description to a
candidate’s CV
Let’s look at some vacancies
Three adverts for API
Technical Authors/Writers
on reed.co.uk from mid-
February 2016……
1.
2.
3.
Search carried out on 15/2/2016
Of the 5,000 UK
Technical Authors
on LinkedIn
173
included “API” in their
profile
Finding a unicorn
“Finding a technical writer who
commands
a high degree of English language
fluency
in addition to possess...
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
...
3. The tools
Help authoring tools
Technical Authors’ tools
Complex tools for complex
problems
Built to suit the needs of the
organisation
Structured authori...
API tools for documentation
API doc writers’ tools
Less sophisticated
Built to suit the developers’
workflow
Low cost, open source
Simple markup
Perception of API tools for
documentation
Perception of API tools for
documentation
Unfamiliar
Flat file CMS
Often require CSS skills
Perception of API tools for
documentation
Can be difficult to install
Poor documentation
Limited support
The tools can do more than
you think
Variables
Single source content
Multi-channel publishing
Conditional text (sort of)
Add review comments and
track changes
Link validation
(but link management can be problematic)
Versioning
What happens when someone falls under a bus?
But API doc systems are
often bespoke
Hopefully we’ll see more
work on
Standardisation
Localisation (Welsh)
Conditional text
Structured content
Link management
...
Help Authoring tools can do
more than you think
Colour coded syntax
Automatic builds
Source control/Binding to Git
HTML5 frameless responsive
web look and feel
What Help authoring tools
can do
Print outputs
Filter content
Collaborative authoring
Hopefully we’ll see more
work on
Exporting to Markdown
Round-tripping Markdown
4. What can we do
about it?
4.1 Recruitment/Skills
Improve skills
More training courses are
emerging
More studying
Share ideas
And understand what the
tools can do
Understand the developers’
tools
Set realistic expectations
You are more likely to find
someone with a wide and
shallow understanding of
programming
Look fo...
Set realistic expectations
Developers should not
abdicate responsibility
Developers may need to
create the code examples
H...
Docs are a team
responsibility
You should be one team
Docs should be part of
the definition of Done
Docs should be part of
...
Run doc sprints
Docs are a team
responsibility
Share the same issue tracker
Share the same review tool?
4.2 Tools/Standards
Improve the tools
It’s getting there
Lightweight DITA may help
Images can be an issue
Make it easy for developers
to write
Set standards
Provide guidelines
Provide templates
Enable them to use their own
tools
Be the content strategist
“Gather it
Organise it
Share it
It’s what you’re good at”
Sarah Maddox, Technical Writer, Google
Learn from each other
TCUK 2016
Summary
What are the takeaways?
Don’t seek a unicorn
Don’t abdicate responsibility
The tools are improving
Authors - improve your ...
Questions
For more information
ellis@cherryleaf.com
@ellispratt
End
© Cherryleaf 2016
Images and screenshots ©
their respective owners
Upcoming SlideShare
Loading in …5
×

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

1,550 views

Published on

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

Published in: Technology

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

×