Learn what went well and what didn’t, when Ilona, a technical writer, and Prabhjot, a software engineer, share the story of revamping the developer documentation website at Twitch. Some hints: getting it done required more than just engineering, content, and design. Together they learned how to “manage up” and that the whole project went better because they worked so well as a team.

1. Lessons learned from revamping
our doc site
API Days, Paris
December, 2019
Ilona Koren-Deutsch
Prabhjot Singh

2. Prabhjot Singh
• Engineering the Twitch API
• More comfortable with Golang than French
• Still plays games written in the 90s

3. Ilona
Koren-Deutsch
● Technical Documentation Manager
● Trained chef and former academic
● Really bad at Super Smash Bros

4. Needs Analysis
If your API is the product, the
documentation is the user interface.

5. Squad Goals
● Increased user satisfaction
● Fewer (and shorter) calls for support
● More people using our APIs
● More and better mods and
extensions

6. Mods and
Extensions • Create ways for viewers and
streamers to interact
• Offer special offers, content, or
in-game items to Twitch viewers
• Let streamers to show off what
mods they are playing to their
community so they can download
and play the mod with their favorite
streamer

7. Important
factors in an
API

8. API doc must
include:
● Authentication
● Status codes
● Error messages
● Sample code
● Terms of use
● Changelog

9. Models for
excellent
developer
portals
The 2019 DevPortal Awards winners:
• Best API Reference Documentation:
Adyen API Explorer
• Best New DX Innovation: NBG Technology
Hub
• Best Onboarding: Nexmo Developer
• Best Accessible DevPortal: Barclays API
Exchange

10. Best in Show
API docs
● TomTom Developer Portal
● Quali Community
● Genesys PureCloud Developer Center
● Stripe
● Heroku
● Twilio

11. Issues with
the current
API docs
• Difficult CMS
• Enormous amount of engineering
time
• Code that devs can’t
copy-and-paste
• Feedback in too many places
• Dev forums
• Discord
• Informal

12. Why OpenAPI is cool

13. OpenAPI
“The ability of APIs to describe their own
structure is the root of all awesomeness
in OpenAPI. “

14. OpenAPI
Allows you to describe your entire API,
including:
● Available endpoints and
operations on each endpoint
● Operation parameters
● Authentication methods
● Contact information, license,
terms of use and other
information

15. Solves our
problems
● Comprehensive API Documentation
● Easy Auto-Generation
● Automates Contract Testing
● Can build Mock APIs

16. Planning

17. Planning • Explore pain-points with the existing
documentation process
• Examine industry practices to set goals
for our docs
• Evaluate OpenAPI Spec as the source of
truth and collaboration for our docs
• Share opinions around different
workflows and reach an agreement
around the process for collaborating
over, creating and maintaining docs

18. Tools

19. Demo Results

24. Live Results

25. Stay tuned!
/dev.twitch.tv/docs/

26. Twitch is hiring!
www.twitch.tv/jobs/

28. Prabhjot: singhfqp@twitch.tv (Twitch: mangotreebird)
Ilona: korendeu@twitch.tv (Twitch: cycene) (Discord: cycene)

29. Reference
Mermade/widdershins
https://github.com/Mermade/widdershins
Slate Docs
https://github.com/slatedocs/slate