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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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

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

5. What causes these issues?
Poor communication
Lack of writer engagement
Inadequate technical review
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

6. Make it about usability01

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

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

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

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?
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

18. Share customer stories
Listeners feel empathy when they hear personal stories
Helps your team keep users in mind
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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
Simple organization
Guidance on high-level design
Code samples and tutorials
Complete and accurate API reference
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

23. Information architecture
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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

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

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

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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!
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

31. UX Strategies for Winning API Documentation @Eric_Cressey #stc17
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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

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
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

38. Resources UX Strategies for Winning API Documentation
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, Ondrej Polacek, 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)
Meng, Michael. “API Documentation: Exploring the Information Needs of Software Developers” (Write the Docs Europe Conference, 2016).
Myers, Brad and Jeffrey Stylos. “Improving API Usability” Communications of the ACM 59.6 (June 2016)
Robillard, Martin. “What Makes APIs Hard to Learn? Answers from Developers” IEEE Software 26.6 (November 2009)
Zibran, Minhaz. “What Makes APIs Difficult to Use?” IJCSNS International Journal of Computer Science and Network Security 8.4 (April 2008)
Zibran, Minhaz, Farjana Eishita, and Chanchal Roy. “Useful, But Usable? Factors Affecting the Usability of APIs” Proceedings of the th Working Conference on Reverse Engineering (October 2011)
Nielsen, Jakob. 10 Usability Heuristics for User Interface Design. heuristics/
UX Strategies for Winning API Documentation
@Eric_Cressey #stc17

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

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