THE STATE OF COMMUNITY
DOCUMENTATION
EMBERFEST 2018
Slide 2
Slide 2 text
EMBERFEST 2018
HELLO
2
Slide 3
Slide 3 text
EMBERFEST 2018
MY NAME IS KENNETH
FRONTEND @ LINKFIRE
CO-EDITOR OF EMBER TIMES
@KENNETHLARSEN
KENNETHLARSEN.ORG
3
Slide 4
Slide 4 text
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 text
OOPS I DID IT AGAIN.
KENNETHLARSEN.ORG/FAILS
5
Slide 6
Slide 6 text
COMMUNITY DOCUMENTATION
1: Why is community documentation important?
2: What is the state of community documentation?
3: How can we improve it?
6
Slide 7
Slide 7 text
1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT? 7
Slide 8
Slide 8 text
1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT?
▸ Proprietary software: Docs included and maintained
8
Slide 9
Slide 9 text
1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT?
▸ Proprietary software: Docs included and maintained
▸ Popular JS Framework: Team that facilitates docs
9
Slide 10
Slide 10 text
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 text
1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT?
WE’RE RESPONSIBLE FOR GREAT COMMUNITY DOCUMENTATION
11
Slide 12
Slide 12 text
EMBERFEST 2018
WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
12
Slide 13
Slide 13 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 13
Slide 14
Slide 14 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 14
Slide 15
Slide 15 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 15
Slide 16
Slide 16 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
Today: ~5000 addons
16
Slide 17
Slide 17 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
README.MD
17
Slide 18
Slide 18 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
BADGES ARE NICE
18
Slide 19
Slide 19 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
HERE’S AN EXAMPLE…
19
Slide 20
Slide 20 text
20
Slide 21
Slide 21 text
21
Slide 22
Slide 22 text
22
Slide 23
Slide 23 text
23
Slide 24
Slide 24 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
SHOW ME THE DATA
24
Slide 25
Slide 25 text
25
Slide 26
Slide 26 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
TEST+RUN
26
Slide 27
Slide 27 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
NPM+INSTALL
27
Slide 28
Slide 28 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
SCORE+OBSERVER
28
Slide 29
Slide 29 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
CONTROLLER+EXTEND
29
Slide 30
Slide 30 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
DS+ATTR = OH NO
30
Slide 31
Slide 31 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
DS+ATTR = OH NO
31
DS.attr(‘string’)
DS.attr()
Slide 32
Slide 32 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
TOM+DALE???
32
Slide 33
Slide 33 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
TOM+DALE???
return UserModel.create({ name: 'Tom Dale' });
Tom Dale!
this.filterEqual(this.store, 'user', {'firstName': 'Tom'}, function(toms) {
33
Slide 34
Slide 34 text
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 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
995 CASES OF UNHELPFUL WORDS
35
Slide 36
Slide 36 text
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 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
“JUST”, “SIMPLY”, “SIMPLE”, “ACTUALLY”, “EASY”, “EASILY”, “OBVIOUSLY”.
37
Slide 38
Slide 38 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
INCONSIDERATE WRITING
“gender favouring, polarising, race related, religion inconsiderate, or other unequal phrasing”.
38
Slide 39
Slide 39 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
2359 CASES OF INCONSIDERATE WRITING
39
Slide 40
Slide 40 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
“IT HAS ALWAYS BEEN LIKE THIS OMG”
- That one guy on Twitter
40
Slide 41
Slide 41 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
CONSIDER THIS…
▸ Master / slave => Primary / Replica
41
Slide 42
Slide 42 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
CONSIDER THIS…
▸ Master / slave => Primary / Replica
▸ Disabled => Turned off
42
Slide 43
Slide 43 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
CULTURAL DIFFERENCES ARE EVERYWHERE
43
Slide 44
Slide 44 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
“MAKE EMBER CLI DOCUMENTATION GREAT AGAIN”
- An embarrassed developer
44
Slide 45
Slide 45 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
CULTURAL DIFFERENCES ARE EVERYWHERE
45
Slide 46
Slide 46 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
CULTURAL DIFFERENCES ARE EVERYWHERE
46
Slide 47
Slide 47 text
WHAT HAVE I DONE 47
Slide 48
Slide 48 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
.
###
# # #
# #
# #
# #
.
&&&
& & &
& &
& &
& &
48
Slide 49
Slide 49 text
2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION?
WHAT ABOUT GENDER?
▸ “he”, “his”, “guys” and “dude”
49
Slide 50
Slide 50 text
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 text
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 text
3: HOW CAN WE IMPROVE IT?
HOW CAN WE IMPROVE IT?
▸ ember-cli-addon-docs
▸ retext-assuming
52
Slide 53
Slide 53 text
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 text
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
54
https://github.com/kennethlarsen/nice-docs
Slide 55
Slide 55 text
No content
Slide 56
Slide 56 text
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