A presentation at EmberFest 2018 in in Amsterdam, Netherlands by Kenneth Larsen
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 👋
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.
The following resources were mentioned during the presentation or are useful additional information.
Here’s what was said about this presentation on social media.
for free. You
can too.