Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Let's bring science into API docs

Lana
September 12, 2023

Let's bring science into API docs

Lana

September 12, 2023
Tweet

More Decks by Lana

Other Decks in Science

Transcript

  1. Who is there? — • Technical writer with 10+ years

    of experience • Specialize in developer’s 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
  2. Previously on… — This is an extension of my talk

    at the Write The Docs Australia 2022
  3. 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
  4. 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
  5. Actually there are much more methods content analysis theoretical sampling

    random sampling strategy Cohen’s Kappa metric correlation analysis length analysis φ-coefficient
  6. Patterns of Knowledge in API Reference Documentation Walid Maalej and

    Martin P. Robillard— • Conclusions: ◦ Detected 12 distinct knowledge types found in API documentation
  7. 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.
  8. Some takeaways — • We can evaluate the content of

    our API documentation in relation to knowledge types
  9. Some takeaways — • We can evaluate the content of

    our API documentation in relation to knowledge types
  10. 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
  11. 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/
  12. 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
  13. 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
  14. 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
  15. 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: ◦ To observe how developers would approach tasks with an API unfamiliar to them. ◦ To analyze which information resources offered by the API documentation developers use to which extent. ◦ To characterize the strategies developers adopt when starting to work with a new API.
  16. 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.
  17. 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.
  18. 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.
  19. 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?
  20. 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
  21. 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
  22. 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 all: enable fast use of the API — implement try-outs and action-oriented documentation.
  23. 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 • What are Honey and Mumford's Learning Styles? https://www.businessballs.com/self-awareness /honey-and-mumfords-learning-styles/
  24. jetbrains.com Let’s stay in touch — @_Unsolved_ Come to the

    writerside @svetlnovikova @lananovikova10 https://lananovikova.tech/ @svetlana-novikova