Thriving in the API doc space

By Tom Johnson / @tomjohnson
idratherbewriting.com

Slides available at
idratherbewriting.com/slides/thriving_in_api_docs

Basic qualifications for API doc jobs

• Familiarity with 1-2 programming languages or other technical platforms
• Experience writing docs for a developer audience
• A portfolio with writing samples demonstrating the above two points

Required: Ability to read code ...

The reason why

Providing value without deep technical knowledge

... the biggest problems with API documentation were also the ones requiring the most technical expertise to solve. Completing, clarifying, and correcting documentation require deep, authoritative knowledge of the API’s implementation. This makes accomplishing these tasks difficult for non-developers or recent contributors to a project. — Martin Robillard and Gias Uddin

The ideal hybrid?

Writers who learned programming?

or

Programmers who learned writing?

Neiman on the technical baseline

Wide, not deep understanding

...the need for writers to have deep technical knowledge diminishes as Tech Comm teams grow in size and as other skills become more important than they are for smaller Tech Comm teams. I’m not claiming that deep technical knowledge is useless. I’m suggesting that (to frame it negatively) neglecting deep technical knowledge has less severe consequences than neglecting content curation, doc tool set, or workflow considerations. — James Rhea

Spectrum of involvement

Techniques for learning code

Building up technical samples

• Document something complex at your current company.
• Write up notes from watching a technical course.
• Develop your own project (e.g., app, API, sample scripts)

Activity: Test Your Knowledge with API Jeopardy

Conclusion!!!

Survey

Please take this short survey so that I can improve the workshop next time: http://bit.ly/apidocsla

Questions?

The end

Tom Johnson
— idratherbewriting.com
— @tomjohnson
— [email protected]