Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Lessons Learned from Revamping Our Doc Site


Published on

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.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Lessons Learned from Revamping Our Doc Site

  1. 1. Lessons learned from revamping our doc site API Days, Paris December, 2019 Ilona Koren-Deutsch Prabhjot Singh
  2. 2. Prabhjot Singh • Engineering the Twitch API • More comfortable with Golang than French • Still plays games written in the 90s
  3. 3. Ilona Koren-Deutsch ● Technical Documentation Manager ● Trained chef and former academic ● Really bad at Super Smash Bros
  4. 4. Needs Analysis If your API is the product, the documentation is the user interface.
  5. 5. Squad Goals ● Increased user satisfaction ● Fewer (and shorter) calls for support ● More people using our APIs ● More and better mods and extensions
  6. 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. 7. Important factors in an API
  8. 8. API doc must include: ● Authentication ● Status codes ● Error messages ● Sample code ● Terms of use ● Changelog
  9. 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. 10. Best in Show API docs ● TomTom Developer Portal ● Quali Community ● Genesys PureCloud Developer Center ● Stripe ● Heroku ● Twilio
  11. 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. 12. Why OpenAPI is cool
  13. 13. OpenAPI “The ability of APIs to describe their own structure is the root of all awesomeness in OpenAPI. “
  14. 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. 15. Solves our problems ● Comprehensive API Documentation ● Easy Auto-Generation ● Automates Contract Testing ● Can build Mock APIs
  16. 16. Planning
  17. 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. 18. Tools
  19. 19. Demo Results
  20. 20. Live Results
  21. 21. Stay tuned! /
  22. 22. Twitch is hiring!
  23. 23. Prabhjot: (Twitch: mangotreebird) Ilona: (Twitch: cycene) (Discord: cycene)
  24. 24. Reference Mermade/widdershins Slate Docs