The State of Community Documentation

EMBERFEST 2018 THE STATE OF COMMUNITY DOCUMENTATION

2 EMBERFEST 2018 👋 HELLO

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

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

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

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

1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT? 7

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

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

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

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

EMBERFEST 2018 WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 12

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 13

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 14

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 15

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

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

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

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

20

21

22

23

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

25

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

WHAT HAVE I DONE 47

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

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

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

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

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

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

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

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

57 IT’S SNACK TIME NOW THOUGH 👋