This document discusses the challenges of API documentation and differences between technical authors and API writers. It outlines that API writers require both strong technical skills like coding abilities as well as writing skills, which can be difficult to find. It also notes differences in tools used for general documentation versus API documentation. Finally, it provides recommendations like improving skills through training, having realistic expectations of skills, improving standards and tools, and making documentation a shared team responsibility.

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

21. Help authoring 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

30. Single source content

31. Multi-channel publishing

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

39. Colour coded syntax

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?

46. 4.1 Recruitment/Skills

47. Improve skills
More training courses are
emerging
More studying
Share ideas
And understand what the
tools can do

48. Understand the developers’
tools

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?

54. 4.2 Tools/Standards

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

62. For more information
ellis@cherryleaf.com
@ellispratt

63. End
© Cherryleaf 2016
Images and screenshots ©
their respective owners