The State of Community Documentation

EMBERCONF 2019 THE STATE OF COMMUNITY DOCUMENTATION

2 EMBERCONF 2019 👋 HELLO

3 EMBERCONF 2019 MY NAME IS KENNETH FRONTEND LEAD @ LINKFIRE EMBER LEARNING CORE TEAM CO-EDITOR OF EMBER TIMES @KENNETHLARSEN KENNETHLARSEN.ORG

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

5 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? 6

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

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

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

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

EMBERCONF 2019 WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 11

2: 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? Today: ~5000 addons 15

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

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

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

19

20

21

22

WISE WORDS

HERE WE GO

SO HELPFUL

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

27

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

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

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

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

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

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

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

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) { 35

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

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

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

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

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 40 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 41

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 42 “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 43

2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? CONSIDER THIS… ▸ Master / slave => Primary / Replica ▸ Whitelist / Blacklist => Allowlist / Denylist 44

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

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

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

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

WHAT HAVE I DONE 49

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

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

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

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

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

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

3: HOW CAN WE IMPROVE IT? “Be careful with Canadian, it’s profane in some cases” 56

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

58 THANK YOU 👋