Aye, Aye, API - What makes Technical Communicators uneasy about API documentation, and what can we...

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

For more information

ellis@cherryleaf.com

@ellispratt

End

© Cherryleaf 2016

Images and screenshots © their respective owners