Let's bring science into API docs

A talk during the apidays Paris December 7 2023

Transcript

1. Let's bring science into API docs — Lana Novikova, Writerside, JetBrains
2. Who is there? — • Technical writer with 10+ years of experience • Specialize in developer and API docs • Mentoring newcomers in the tech writing field and teaching IT students technical communication • Developing product for documentarians by documentarians #Writerside • Learning neuroscience, cognitive psychology, and andragogy in a spare time
3. Previously on… — This is an extension of my talk at the Write The Docs Australia 2022
4. JetBrains: The Drive to Develop — Pattern recognition —
5. Pattern recognition — • What we do: Structure API documentation according some industry-wide, expected patterns • What is it based on: Pattern recognition ◦ Humans match the information received with the information already stored in the brain ◦ An early example of this is learning the alphabet in order Origin: neuroscience To dig deeper: • Patterns of Knowledge in API Reference Documentation Walid Maalej and Martin P. Robillard
6. Patterns of Knowledge in API Reference Documentation Walid Maalej and Martin P. Robillard • Methodology: Approached API reference documentation of JDK 6 and .NET 4.0 using content analysis method • Goal: to discover how different knowledge types are distributed through API documentation
7. Actually there are much more methods content analysis theoretical sampling random sampling strategy Cohen’s Kappa metric correlation analysis length analysis φ-coefficient
8. Patterns of Knowledge in API Reference Documentation Walid Maalej and Martin P. Robillard— • Conclusions: ◦ Detected 12 distinct knowledge types found in API documentation
10. Patterns of Knowledge in API Reference Documentation Walid Maalej and Martin P. Robillard— • Conclusions: ◦ Detected 12 distinct knowledge types found in API documentation ◦ Documentation for the JDK and .NET differ. JDK documentation contains more conceptual knowledge whereas .NET contains more information about the structure of the API and its usage patterns.
14. Some takeaways — • We can evaluate the content of our API documentation in relation to knowledge types
15. Some takeaways — • We can evaluate the content of our API documentation in relation to knowledge types
16. Some takeaways — • We can evaluate the content of our API documentation in relation to knowledge types • Develop documentation templates that are adapted to the knowledge commonly associated with different types of API elements
17. Some takeaways — • We can evaluate the content of our API documentation in relation to knowledge types • Develop documentation templates that are adapted to the knowledge commonly associated with different types of API elements If you want to get some ready-to-use template or want to participate in developing them - come to The Good Docs Project https://thegooddocsproject.dev/
18. JetBrains: The Drive to Develop — Learning styles —
19. Learning styles — • What we do: Imagine API usage as a learning process, make it easier for people with various learning styles • What is it based on: Learning style ◦ There is no single "most effective" way of learning; it varies from person-to-person. ◦ An individual's learning method will be different in different situations, and likely change over time Origin: cognitive science and theory of learning To dig deeper: • How Developers Use API Documentation: An Observation Study by Michael Meng, Stephanie Steinhardt, and Andreas Schubert. Merseburg University of Applied Sciences
20. Learning styles: David Kolb VAK Felder-Silverman Honey-Mumford 4MAT Gregorc Hermann Brain Dominance Instrument
21. Learning styles: David Kolb’s model • Kolb defined 4 learning styles: ◦ Accommodator: strong in "hands-on" practical doing ◦ Converger: strong in practical "hands-on" application of theories ◦ Diverger: strong in imaginative ability and discussion ◦ Assimilator: strong in inductive reasoning
22. Learning styles: Peter Honey and Alan Mumford’s model • Activist: Learn by doing, and happy to jump in. • Reflector: Learn through observation and reflecting on results • Theorist: Like to understand the theory behind actions • Pragmatist: Need to be able to see how they apply their learning to the real world
23. How Developers Use API Documentation: An Observation Study by Michael Meng, Stephanie Steinhardt, and Andreas Schubert • Methodology: Active observation, screencasts, and verbal protocols of participant activities during the test, researchers evaluated success rate, time spent on tasks, and usage of documentation and content categories. • Goal: ◦ Observe how developers would approach tasks with an API unfamiliar to them. ◦ Analyze which information resources offered by the API documentation developers use to which extent. ◦ Characterize the strategies developers adopt when starting to work with a new API.
25. How Developers Use API Documentation: An Observation Study by Michael Meng, Stephanie Steinhardt, and Andreas Schubert • Conclusions: ◦ On average, participants used API documentation about 49% of the time (Min: 31%, Max: 68%). ◦ The content category referred to most often is the API reference, followed by the Recipes page.
26. 49 %
27. How Developers Use API Documentation: An Observation Study by Michael Meng, Stephanie Steinhardt, and Andreas Schubert • Conclusions: ◦ On average, participants used API documentation about 49% of the time (Min: 31%, Max: 68%). ◦ The content category referred to most often is the API reference, followed by the Recipes page. ◦ There is considerable variation between participants with respect to the time they allocate to individual content categories.
30. How Developers Use API Documentation: An Observation Study by Michael Meng, Stephanie Steinhardt, and Andreas Schubert • Conclusions: ◦ On average, participants used API documentation about 49% of the time (Min: 31%, Max: 68%). ◦ The content category referred to most often is the API reference, followed by the Recipes page. ◦ there is considerable variation between participants with respect to the time they allocate to individual content categories. ◦ Based on this data the researchers defined three information-seeking software developer personae and the approaches they use when looking for information to put a new API to work.
31. How Developers Use API Documentation: An Observation Study by Michael Meng, Stephanie Steinhardt, and Andreas Schubert Three developer learning personae*: • Systematic learners • Opportunistic learners • Pragmatic learners * Based on Clarke, S. (2007). What is an end user software engineer?
32. Systematic learners seek to understand the API before they use it.
33. Opportunistic learners seek to get started as quickly as possible without first understanding the API
34. Pragmatic learners combine elements of both approaches
35. Systematic -> Theorist Opportunistic -> Activist
36. How Developers Use API Documentation: An Observation Study by Michael Meng, Stephanie Steinhardt, and Andreas Schubert Is there a correlation between success rate and learning style?
37. Some takeaways — • Respect the different strategies that developers adopt when approaching a new API
38. Some takeaways — • Respect the different strategies that developers adopt when approaching a new API ◦ For opportunistic developers, make complete and comprehensive code examples and an ability to hide everything else and connect text-to-code
41. Some takeaways — • Respect the different strategies that developers adopt when approaching a new API ◦ For opportunistic developers, make complete and comprehensive code examples and an ability to hide everything else and connect text-to-code ◦ For systematic — provide important information redundantly and give relevant background knowledge
42. Тут надо какой-то пример концептуальной информации и бэкграунда разлитого в апи референсе
43. Some takeaways — • Respect the different strategies that developers adopt when approaching a new API ◦ For opportunistic developers, make complete and comprehensive code examples and an ability to hide everything else and connect text-to-code ◦ For systematic — provide important information redundantly and give relevant background knowledge ◦ For pragmatic (and all) —give a way to jump start using an API.
44. Пример фаст аксеса - трай ауты и простой вход
45. Пример фаст аксеса - трай ауты и простой вход
46. Пример фаст аксеса - трай ауты и простой вход
47. And you too!
48. Resources mentioned to dive deeper — • Patterns of Knowledge in API Reference Documentation Walid Maalej and Martin P. Robillard https://www.cs.mcgill.ca/~martin/papers/tse20 13a.pdf • How Developers Use API Documentation: An Observation Study by Michael Meng, Stephanie Steinhardt, and Andreas Schubert https://sigdoc.acm.org/wp-content/uploads/20 19/01/CDQ18002_Meng_Steinhardt_Schubert. pdf
49. jetbrains.com Let’s stay in touch — @_Unsolved_ Come to the writerside We support API docs @svetlnovikova @lananovikova10 @svetlana-novikova