New Relic hired an external trainer to teach members of the Tech Docs and UX teams REST API documentation best practices.
Tthe team members already learnt about API reference writing through documenting them, and from classes aimed at engineers. Emphatic knowledge gaps appeared on a fundamental level.
Needs of techwriter- & UX team from training
Stronger footing in APIs
Run API calls and test them how they work
Need to uplevel skills in techwriter team fast
Confidence to write rich content (use cases, tasks), need deeper understanding of APIs
Toolchains and workflows matching needs of modern users
7 training principles
Consider the audience: mixed background, typical techwriter level but not engineer --» explain technical topics more slowly, explicitly. Do not assume programming experience: Fine-tune to audience needs because training takes a lot of resources. Small class.
Adjust agenda to student interest, address concepts.
Ensure low-friction interactivity, but not command-performance: frequently scheduled breaks for questions.
Liven up tech content: move out of technology often, with interesting and relevant examples.
The 80/20 rule: teach the first 20%, and students can self-teach the rest if they meet it.
Boundaries around content for beginners, to inspire and empower, to reduce impostor syndrome or paralysis from overwhelm.
Multimodal learning: first learn. Then practice in frequent small labs. Then make students answer other students' questions, the act of explanation consolidates their own understanding.
How did the training affect their regular jobs a few months later
Higher confidence in discussions on:
what needed to be included in the API docs,
how their APIs work,
how their flavor of graphQL fits into the overall product landscape.
Being able to ask more directed, particular questions around the APIs they are documenting.
Sign up to our Developer Portal Newsletter so that you never miss out on the latest API The Docs recaps and our devportal, API documentation and Developer Experience research publications.