User Experience Strategies for Winning API Documentation

1. User Experience Strategies for Winning API Documentation Eric Cressey Principal Info Developer Symantec Corporation May 8, 2017

2. Why “winning” documentation? • Winning is the best outcome • Winning is measurable • We want measurably successful documentation @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

3. Agenda • Strategies for better preparation • Strategies for building winning API documentation @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

4. The API user experience Robillard2009, p. 30 @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

5. What causes these issues? • Poor communication • Lack of writer engagement • Inadequate technical review http://dilbert.com/strip/1995-08-28 @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

6. Make it about usability 01

7. Usability goes beyond docs Zibran, Eishita, and Roy 2011, p. 153 @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

8. Public APIs are forever • Your team gets one chance to get it right • Most API usability issues must be addressed during API design @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

9. Methods for evaluating usability • Heuristic evaluations • Usability studies • Interviews • Surveys @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

10. Heuristic evaluations • Do names match expectations? • Are names clear and obvious? • Is the design consistent? • Does it default to correct behavior? • Are errors helpful? • Can you use it efficiently? @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

11. Usability studies • Identify issues documentation and API structure • Have developers come in and use the API • Encourage them to talk through their actions @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

12. Interviews and surveys • Identify user experience and documentation issues • Quick, easy, and cheap • Can be done at any time • Use them to establish metrics and create personas @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

13. Collecting user feedback is key • Make it part of your process • Do it as often as you can • Record your sessions and take good notes • Track responses over time @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

14. Be a team player 02

15. Get involved early • Cultivate PO relationship • Ask about feature roadmap, user stories, customer requests, business logic for integrations @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

16. Position yourself for success • Study and use the API • Investigate the technology the API is built on • Learn to read code • Learn code style and naming conventions @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

17. Stay engaged • Lurk in code reviews and design discussions • Review API design for usability • Get high-level API design information • Get technical feedback early @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

18. Share customer stories • Listeners feel empathy when they hear personal stories • Helps your team keep users in mind https://en.wikipedia.org/wiki/Hero%27s_journey @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

19. Share your wins, too • People like being part of a winning effort • Conditions your team to help you win more • Creates a user-first team mentality • Replenishes goodwill @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

20. Use goodwill wisely • It’s a finite resource • Use it when you ask for stuff from teammates or customers • Replenish it by being thankful and respectful

21. Meet user needs 03

22. Hierarchy of API user needs Search Complete and accurate API reference Simple organization Guidance on high-level design Code samples and tutorials @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

23. Information architecture https://developers.google.com/maps/documentation/javascript/tutorial @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

24. Card sorting • Regular for new information • Reverse to validate existing • Aim for distinct containers

25. API reference • Biggest source of API usability issues • SpringRestDocs and Swagger2Markup for REST APIs https://stripe.com/docs/api#account @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

26. Developer’s guide • Getting started section • Minimize “time to first hello world” • Use cases, in-depth tutorials, samples • Business logic https://stripe.com/docs @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

27. Interactive testing and samples • Faster onboarding • Swagger petstore, Amazon scratchpad, etc. @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

28. Why are samples important? • 55% of developers learn through code samples • Developers don’t want to start from scratch @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

29. Types of code samples • Short samples for demonstrating basics • Tutorials for in-depth coverage of a specific task in API • Code segments from complete applications @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

30. Code sample formatting tips • Use a style guide • Use white space for logical code chunks • Use comments to discuss code flow, non-obvious concepts • Make sure samples stand alone and work as formatted! @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

31. https://stripe.com/docs/charges @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

32. Search • Some people don’t browse • Important even for single-page documentation • Useful for analytics • Lunr.js is an option if you want to build your own @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

33. Analytics • Search terms • Pages visited after search • User page flows • Pages per visit @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

34. Measure everything 04

35. Measure everything • Keep track of user feedback • API adoption, customer retention, support escalations • API documentation analytics • Get fresh data often @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

36. Metrics provide visibility • Problems with the API or documentation • Improvements @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

37. Ways to win • Frame documentation as a usability task • Stay engaged in the development process • Make sure your documentation meets user needs • Measure everything and do it often @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

38. Resources • J. Bloch. How to Design a Good API and Why it Matters. OOPSLA, Companion to the 21st ACM SIGPLAN Symposium on Object-Oriented Programming Systems, Languages, and Applications (October 2006) 506–507. • Grill, Thomas, OndrejPolacek, and Manfred Tscheligi. “Methods Toward API Usability: A Structural Analysis of Usability Problem Categories” Proceedings of the 4th International Conference on Human-Centered Software Engineering (October 2012) 164-180. • Meng, Michael. “API Documentation: Exploring the Information Needs of Software Developers” (Write the Docs Europe Conference, 2016). https://www.youtube.com/watch?v=soQSOBwiXdA • Myers, Brad and Jeffrey Stylos. “Improving API Usability” Communications of the ACM 59.6 (June 2016) 62-69. https://cacm.acm.org/magazines/2016/6/202645-improving-api-usability/abstract • Robillard, Martin. “What Makes APIs Hard to Learn? Answers from Developers” IEEE Software 26.6 (November 2009) 27-34. http://ieeexplore.ieee.org/document/5287006/?reload=true • Zibran, Minhaz. “What Makes APIs Difficult to Use?” IJCSNS International Journal of Computer Science and Network Security 8.4 (April 2008) 255-261. • Zibran, Minhaz, FarjanaEishita, and Chanchal Roy. “Useful, But Usable? Factors Affecting the Usability of APIs” Proceedings of the 2011 18th Working Conference on Reverse Engineering (October 2011) 151-155. • Nielsen, Jakob. 10 Usability Heuristics for User Interface Design. https://www.nngroup.com/articles/ten-usability-heuristics/ @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

39. Questions? @Eric_Cressey #stc17 UX Strategies for Winning API Documentation

40. Thank you! Eric Cressey eric_cressey@symantec.com @Eric_Cressey @Eric_Cressey #stc17 UX Strategies for Winning API Documentation