Tweet
Tweet

Slide 1

Slide 1 text

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

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

JetBrains: The Drive to Develop — Pattern recognition —

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

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

Slide 9

Slide 9 text

No content

Slide 10

Slide 10 text

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.

Slide 11

Slide 11 text

No content

Slide 12

Slide 12 text

No content

Slide 13

Slide 13 text

No content

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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/

Slide 18

Slide 18 text

JetBrains: The Drive to Develop — Learning styles —

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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.

Slide 23

Slide 23 text

No content

Slide 24

Slide 24 text

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.

Slide 25

Slide 25 text

49 %

Slide 26

Slide 26 text

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.

Slide 27

Slide 27 text

No content

Slide 28

Slide 28 text

No content

Slide 29

Slide 29 text

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.

Slide 30

Slide 30 text

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?

Slide 31

Slide 31 text

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

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

Pragmatic learners combine elements of both approaches

Slide 34

Slide 34 text

Systematic -> Theorist Opportunistic -> Activist

Slide 35

Slide 35 text

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

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

No content

Slide 38

Slide 38 text

No content

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

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.

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

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

Slide 45

Slide 45 text

And you too!

Slide 46

Slide 46 text

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/

Slide 47

Slide 47 text

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