Let's bring science into API docs

Transcript

1. Let's bring
   science into API
   docs
   —
   Lana Novikova, Writerside, JetBrains
   

   View Slide

2. 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
   

   View Slide

3. Previously on…
   —
   This is an extension of my talk at the Write The
   Docs Australia 2022
   

   View Slide

4. JetBrains: The Drive to Develop
   —
   Pattern
   recognition
   —
   

   View Slide

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
   

   View Slide

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
   

   View Slide

7. Actually there are much
   more methods
   content analysis
   theoretical sampling
   random sampling
   strategy
   Cohen’s Kappa metric
   correlation analysis
   length analysis
   φ-coefficient
   

   View Slide

8. Patterns of Knowledge in API Reference
   Documentation Walid Maalej and Martin P. Robillard—
   ● Conclusions:
   ○ Detected 12 distinct knowledge types found in API
   documentation
   

   View Slide

9. View Slide

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.
    

    View Slide

11. View Slide

12. View Slide

13. View Slide

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

    View Slide

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

    View Slide

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
    

    View Slide

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/
    

    View Slide

18. JetBrains: The Drive to Develop
    —
    Learning
    styles
    —
    

    View Slide

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
    

    View Slide

20. 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
    

    View Slide

21. 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
    

    View Slide

22. 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.
    

    View Slide

23. View Slide

24. 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.
    

    View Slide

25. 49 %
    

    View Slide

26. 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.
    

    View Slide

27. View Slide

28. View Slide

29. 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.
    

    View Slide

30. 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?
    

    View Slide

31. Systematic learners
    seek to understand
    the API before they
    use it.
    

    View Slide

32. Opportunistic
    learners seek to get
    started as quickly as
    possible without first
    understanding the API
    

    View Slide

33. Pragmatic
    learners combine
    elements of both
    approaches
    

    View Slide

34. Systematic -> Theorist Opportunistic -> Activist
    

    View Slide

35. Some takeaways
    —
    ● Respect the different strategies that
    developers adopt when approaching
    a new API
    

    View Slide

36. 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
    

    View Slide

37. View Slide

38. View Slide

39. 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
    

    View Slide

40. Тут надо какой-то пример
    концептуальной информации и
    бэкграунда разлитого в апи референсе
    

    View Slide

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
    ● For all: enable fast use of the API — implement try-outs and
    action-oriented documentation.
    

    View Slide

42. Пример фаст аксеса - трай ауты и
    простой вход
    

    View Slide

43. Пример фаст аксеса - трай ауты и
    простой вход
    

    View Slide

44. Пример фаст аксеса - трай ауты и
    простой вход
    

    View Slide

45. And you too!
    

    View Slide

46. 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/
    

    View Slide

47. jetbrains.com
    Let’s stay in touch
    —
    @_Unsolved_
    Come to the writerside
    @svetlnovikova
    @lananovikova10
    https://lananovikova.tech/
    @svetlana-novikova
    

    View Slide