The State of Community Documentation

A presentation at EmberFest 2018 in October 2018 in Amsterdam, Netherlands by Kenneth Larsen

Slide 1

Slide 1

EMBERFEST 2018 THE STATE OF COMMUNITY DOCUMENTATION

Slide 2

Slide 2

2 EMBERFEST 2018 👋 HELLO

Slide 3

Slide 3

3 EMBERFEST 2018 MY NAME IS KENNETH FRONTEND @ LINKFIRE CO-EDITOR OF EMBER TIMES @KENNETHLARSEN KENNETHLARSEN.ORG

Slide 4

Slide 4

EMBERFEST 2018 “I RE-READ THE EMBER TIMES EVERY SINGLE DAY. IT SIMPLY MAKES ME A BETTER HUMAN BEING.” - Tom Dale, SproutCore enthusiast 4

Slide 5

Slide 5

5 OOPS I DID IT AGAIN. KENNETHLARSEN.ORG/FAILS

Slide 6

Slide 6

6 COMMUNITY DOCUMENTATION 1: Why is community documentation important? 2: What is the state of community documentation? 3: How can we improve it?

Slide 7

Slide 7

1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT? 7

Slide 8

Slide 8

1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT? ▸ Proprietary software: Docs included and maintained 8

Slide 9

Slide 9

1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT? ▸ Proprietary software: Docs included and maintained ▸ Popular JS Framework: Team that facilitates docs 9

Slide 10

Slide 10

1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT? ▸ Proprietary software: Docs included and maintained ▸ Popular JS Framework: Team that facilitates docs ▸ Ember addon: ??? 10

Slide 11

Slide 11

1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT? 11 WE’RE RESPONSIBLE FOR GREAT COMMUNITY DOCUMENTATION

Slide 12

Slide 12

EMBERFEST 2018 WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 12

Slide 13

Slide 13

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 13

Slide 14

Slide 14

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 14

Slide 15

Slide 15

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 15

Slide 16

Slide 16

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? Today: ~5000 addons 16

Slide 17

Slide 17

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? README.MD 17

Slide 18

Slide 18

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? BADGES ARE NICE 18

Slide 19

Slide 19

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? HERE’S AN EXAMPLE… 19

Slide 20

Slide 20

20

Slide 21

Slide 21

21

Slide 22

Slide 22

22

Slide 23

Slide 23

23

Slide 24

Slide 24

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? SHOW ME THE DATA 24

Slide 25

Slide 25

25

Slide 26

Slide 26

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? TEST+RUN 26

Slide 27

Slide 27

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? NPM+INSTALL 27

Slide 28

Slide 28

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? SCORE+OBSERVER 28

Slide 29

Slide 29

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? CONTROLLER+EXTEND 29

Slide 30

Slide 30

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? DS+ATTR = OH NO 30

Slide 31

Slide 31

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? DS+ATTR = OH NO DS.attr(‘string’) DS.attr() 31

Slide 32

Slide 32

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? TOM+DALE??? 32

Slide 33

Slide 33

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? TOM+DALE??? return UserModel.create({ name: 'Tom Dale' }); <option value="1">Tom Dale!</option> this.filterEqual(this.store, 'user', {'firstName': 'Tom'}, function(toms) { 33

Slide 34

Slide 34

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? UNHELPFUL PHRASINGS ▸ “Simply run the tests. Just type npm test” ▸ “Just write your own compiler, then it simply works”. 34

Slide 35

Slide 35

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 995 CASES OF UNHELPFUL WORDS 35

Slide 36

Slide 36

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 995 CASES OF UNHELPFUL WORDS THAT’S ONLY 0.07% OF THE WORDS 36

Slide 37

Slide 37

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? “JUST”, “SIMPLY”, “SIMPLE”, “ACTUALLY”, “EASY”, “EASILY”, “OBVIOUSLY”. 37

Slide 38

Slide 38

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 38 INCONSIDERATE WRITING “gender favouring, polarising, race related, religion inconsiderate, or other unequal phrasing”.

Slide 39

Slide 39

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 2359 CASES OF INCONSIDERATE WRITING 39

Slide 40

Slide 40

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 40 “IT HAS ALWAYS BEEN LIKE THIS OMG” - That one guy on Twitter

Slide 41

Slide 41

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? CONSIDER THIS… ▸ Master / slave => Primary / Replica 41

Slide 42

Slide 42

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? CONSIDER THIS… ▸ Master / slave => Primary / Replica ▸ Disabled => Turned off 42

Slide 43

Slide 43

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? CULTURAL DIFFERENCES ARE EVERYWHERE 43

Slide 44

Slide 44

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 44 “MAKE EMBER CLI DOCUMENTATION GREAT AGAIN” - An embarrassed developer

Slide 45

Slide 45

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? CULTURAL DIFFERENCES ARE EVERYWHERE 45

Slide 46

Slide 46

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? CULTURAL DIFFERENCES ARE EVERYWHERE 46

Slide 47

Slide 47

WHAT HAVE I DONE 47

Slide 48

Slide 48

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 🤠 ### # # # 👇 # # 👇 # # # # 👢 👢 . 🤠 &&& & & & 👇 & & 👇 & & & & 👢 👢 . 48

Slide 49

Slide 49

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? WHAT ABOUT GENDER? ▸ “he”, “his”, “guys” and “dude” 49

Slide 50

Slide 50

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? SUMMARY ▸ Readmes are too cluttered ▸ Blueprint documentation needs adjustments ▸ We need a separate space for documentation ▸ We’re doing OK with inclusive writings ▸ Cultural differences will always exist - be aware! 50

Slide 51

Slide 51

3: HOW CAN WE IMPROVE IT? HOW CAN WE IMPROVE IT? ▸ ember-cli-addon-docs ▸ Write markdown ▸ Interactive component demos ▸ Auto generated API documentation 51

Slide 52

Slide 52

3: HOW CAN WE IMPROVE IT? HOW CAN WE IMPROVE IT? ▸ ember-cli-addon-docs ▸ retext-assuming 52

Slide 53

Slide 53

3: HOW CAN WE IMPROVE IT? HOW CAN WE IMPROVE IT? ▸ ember-cli-addon-docs ▸ retext-assuming ▸ alex (or ember-cli-alex) 53

Slide 54

Slide 54

3: HOW CAN WE IMPROVE IT? WORK IN PROGRESS… ▸ CLI tool that fetches an addon ▸ Runs automated analysis ▸ Returns a list of issues you can fix https://github.com/kennethlarsen/nice-docs 54

Slide 55

Slide 55

Slide 56

Slide 56

WHAT DID WE LEARN ▸ Documentation is crucial for a healthy community ▸ We’re all responsible for addon documentation ▸ The readme is too cluttered and so is the blueprint ▸ The level of considerate writing is good, but can be improved ▸ There’s tools to help you. Use them. Make them default. 56

Slide 57

Slide 57

57 IT’S SNACK TIME NOW THOUGH 👋