A presentation at EmberConf 2019 in in Portland, OR, USA by Kenneth Larsen
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 👋
Ember takes pride in having great documentation. So much that we even have a Learning Team dedicated to keeping the official documentation great.
But what is the actual state of community documentation?
After scraping and analysing just about 5000 readme files from Ember addons created by the community, I’ll present common pitfalls and ways to improve our community documentation.
Here’s what was said about this presentation on social media.
for free. You
can too.