aye, aye, api - what makes technical communicators uneasy about api documentation, and what can we...
TRANSCRIPT
Aye, Aye, API What makes
Technical Communicators
uneasy about API documentation and
what can we do about it?
Ellis Pratt
Overview1. 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 content
Localise
API Writer
Reference-based content*
Technical stuff to a technical audience
Single use document
English only
What API doc writers do
* Mostly
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
2. The skills required
Skills requiredTechnical 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)
Skills required -Take 2Technical 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)
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 possessing a deep technical knowledge of Java, Python, C++, .NET, Ruby, and more
is like finding a unicorn.”Tom Johnson
Flickr image: Owlana
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
3. The tools
Help authoring tools
Technical Authors’ toolsComplex tools for complex problems
Built to suit the needs of the organisation
Structured authoring
Versioning
Multilingual
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
Image:Tom Johnson
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 for writers who can read code, rather than write it
Set realistic expectationsDevelopers 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
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
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 skills
Questions
End
© Cherryleaf 2016
Images and screenshots © their respective owners