Writers are experts at dealing with ambiguity. We do highly technical work, frequently without formal CS education. We find ways to make content out of wireframes, code strings, Jira tickets, and spit. We especially fall back on these skills when documenting APIs, where the information is often scarce and our understanding of the APIs and how they’re used can feel abstracted from the product. But APIs aren’t just for reference anymore. With an update to our New Relic developer site in the works, we needed to up our game. In February, we hired Chris Cowell to teach members of the Tech Docs and UX teams REST API basics. The class was a huge success because it covered the topics we needed to learn, but also because Chris created a lively, interactive, accessible experience. Even those of us who have been documenting APIs for years came away with deeper understanding and greater confidence. In this talk, Chris Cowell and Michelle Fredette discuss high- and low-level knowledge gaps the training addressed, and how the class has enriched our docs and UX work, as well as our relationships with SMEs. We’ll share some basic tips and finally, we’ll talk about how classes like this one—which a participant called, “the single most effective technical training I’ve ever received”—are fundamental to the expanding complexity of our careers.

1. Eight hours to API literacy:
a fast, fun on-ramp for writers
Michelle Fredette
mfredette@newrelic.com
docs.newrelic.com
Chris Cowell
chris@christophercowell.llc
www.christophercowell.llc

2. Setting the scene

3. What we wanted

4. 7 training principles
How to
API

5. 1. Consider the
audience

6. 1. Use Google to find the longitude and latitude of
Stockholm
2. Use curl with this URL:
http://sunrise.com/api/<LAT>,<LONG>

7. 2. Student interests drive the agenda

8. What are REST APIs?
How do you use REST APIs?
What are examples of good REST API documentation?
What is GraphQL?
REST API Documentation best practices?

9. 3. Low-friction interactivity

10. Questions about request-response model?

11. Questions about reusing
web concepts?

12. 4. Make tech less dry

13. 5. Use the
Pareto Principle
(80/20 rule)

14. 6. Draw boundaries
around content

15. 7. Multimodal learning

18. Prepackaged training
is rarely what
you need or want

19. Questions?
mfredette@newrelic.com chris@christophercowell.llc

20. Image credits
cassette tape: Pixabay license. Image by OpenClipart-Vectors from Pixabay.
https://pixabay.com/vectors/cassette-tape-recorder-vintage-old-2025403/
target: Public Domain (CC0). https://pixnio.com/sport/archery-arrow-medieval-sport-target-traditional-wooden-wood
normal distribution: Pixabay license. Image by OpenClipart-Vectors from Pixabay.
https://pixabay.com/vectors/distribution-normal-statistics-159626/
cat in box: Public Domain. https://en.wikipedia.org/wiki/File:Cat_into_the_box.jpg
Alan Turing: Public Domain. https://commons.wikimedia.org/wiki/File:Alan_Turing_Aged_16.jpg
Typewriter: royalty free. https://www.pikrepo.com/fatiu/typing-vintage-typewriter-b-w
Socrates: public domain. https://commons.wikimedia.org/wiki/File:Socrates_Pio-Clementino_Inv314.jpg
Desert: Nepenthes / CC-BY-SA 3.0 https://en.wikipedia.org/wiki/Desert#/media/File:Rub_al_Khali_002.JPG
Speak & Spell: Bill Bertram, CC-BY-2.5. https://commons.wikimedia.org/wiki/File:TI_SpeakSpell.jpg
Pareto: public domain. https://en.wikipedia.org/wiki/Vilfredo_Pareto#/media/File:Vilfredo_Pareto_1870s2.jpg
Typewriter:pixabay license. Image by Annie Spratt. https://pixabay.com/photos/vintage-typewriter-plant-book-2168174/
Stockholm sunrise: Pexels license. https://www.pexels.com/photo/stockholm-sunrise-110737/
Fence: pixabay license. https://pixabay.com/photos/palisade-fence-boards-fence-slats-1588766/
Cat and Dog: public domain. https://www.publicdomainpictures.net/en/view-image.php?image=3081&picture=cat-and-dog
Sandwich: Creative Commons Attribution-Share Alike 4.0 license. https://commons.wikimedia.org/wiki/File:Prepackaged_sandwich.jpg