Writing Engaging and Informative API Documentation for Third Parties
Designed for Backend software engineers and developer advocates responsible for publishing API documentation for external partners and integrators. to spark real collaboration and high-energy learning.
A 90-minute virtual workshop for backend engineers and developer advocates who have recently been tasked with making their APIs accessible to outside partners. Many participants have deep technical expertise but struggle to communicate API usage clearly outside their immediate team. Common pain points include 'wall-of-text' reference docs, lack of context for real-world use, and answering the same integration questions repeatedly.
Mystery API Challenge
Present participants with a one-paragraph, obfuscated API doc (e.g., function names disguised, context missing) and ask them to guess what the API actually does. Then reveal the actual purpose and usage. This sparks curiosity about what’s missing when docs aren’t designed for outsiders.
Tap to view the full activity.
Why this works
Activates natural curiosity and primes participants to notice clarity gaps, leveraging the 'information gap' effect for engagement.
Debunking API Doc Myths
Present three common myths (e.g., 'Developers don’t need examples', 'Reference docs are enough', 'More detail always helps'). Poll the group on which they believe. Unpack why these are misconceptions with real examples.
Tap to view the full activity.
Why this works
Reveals and challenges existing beliefs; confronting misconceptions is a cognitive trigger for deeper learning.
Emoji Confidence Check
Ask everyone to pick an emoji in chat or on cards that represents how confident they feel writing API docs for an unfamiliar audience. Invite 2–3 volunteers to briefly share why they chose their emoji; no one is put on the spot.
Tap to view the full activity.
Why this works
Sets a low-bar for participation, creates psychological safety, and surfaces group sentiment non-verbally.
Lightning Doc Rewrite Race
Split into small groups. Give each group a clunky, jargon-heavy API doc snippet. Challenge them to rewrite it for clarity and engagement in just 5 minutes, then share for instant group applause. Quickest improvements win digital kudos or a fun sound effect.
Tap to view the full activity.
Why this works
Injects competitive energy, active practice, and peer validation to boost retention.
The Partner Dilemma Case
Show an anonymized support ticket from a real third-party integrator struggling with unclear docs ('I’m getting 401 errors—am I missing a header?'). Invite the group to diagnose what went wrong in the docs and propose a fix.
Tap to view the full activity.
Why this works
Anchors abstract skills in genuine developer pain, building empathy and contextual problem-solving.
Doc Journey Map Reflection
Invite participants to privately sketch or outline the journey a third-party dev experiences—from first reading the API docs to completing a working integration. Ask: 'Where might they stumble? What could delight them?' Share key reflections aloud or in chat.
Tap to view the full activity.
Why this works
Promotes personal connection, active reflection, and systems thinking—building motivation to improve docs for real users.
Sign up to unlock 3 more activities
Get the full pack, facilitation flow, and more ready-to-run ideas.