1 / 40

User Experience Strategies for Winning API Documentation

User Experience Strategies for Winning API Documentation. Eric Cressey Principal Info Developer Symantec Corporation. May 8, 2017. Why “winning” documentation?. Winning is the best outcome Winning is measurable We want measurably successful documentation. @ Eric_Cressey #stc17.

jessea
Download Presentation

User Experience Strategies for Winning API Documentation

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  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

More Related