The State of Community Documentation

The State of Community Documentation

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.

07964a2e495aecd9045adcc0af06c7e4?s=128

Kenneth Larsen

October 12, 2018
Tweet

Transcript

  1. THE STATE OF COMMUNITY DOCUMENTATION EMBERFEST 2018

  2. EMBERFEST 2018 HELLO 2

  3. EMBERFEST 2018 MY NAME IS KENNETH FRONTEND @ LINKFIRE CO-EDITOR

    OF EMBER TIMES @KENNETHLARSEN KENNETHLARSEN.ORG 3
  4. 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 5

  6. COMMUNITY DOCUMENTATION 1: Why is community documentation important? 2: What

    is the state of community documentation? 3: How can we improve it? 6
  7. 1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT? 7

  8. 1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT? ▸ Proprietary software: Docs

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

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

    included and maintained ▸ Popular JS Framework: Team that facilitates docs ▸ Ember addon: ??? 10
  11. 1: WHY IS COMMUNITY DOCUMENTATION IMPORTANT? WE’RE RESPONSIBLE FOR GREAT

    COMMUNITY DOCUMENTATION 11
  12. EMBERFEST 2018 WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 12

  13. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 13

  14. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 14

  15. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 15

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

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

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

    NICE 18
  19. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? HERE’S AN

    EXAMPLE… 19
  20. 20

  21. 21

  22. 22

  23. 23

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

    THE DATA 24
  25. 25

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

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

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

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

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

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

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

  33. 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
  34. 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
  35. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? 995 CASES

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

    OF UNHELPFUL WORDS THAT’S ONLY 0.07% OF THE WORDS 36
  37. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? “JUST”, “SIMPLY”,

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

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

    OF INCONSIDERATE WRITING 39
  40. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? “IT HAS

    ALWAYS BEEN LIKE THIS OMG” - That one guy on Twitter 40
  41. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? CONSIDER THIS…

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

    ▸ Master / slave => Primary / Replica ▸ Disabled => Turned off 42
  43. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? CULTURAL DIFFERENCES

    ARE EVERYWHERE 43
  44. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? “MAKE EMBER

    CLI DOCUMENTATION GREAT AGAIN” - An embarrassed developer 44
  45. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? CULTURAL DIFFERENCES

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

    ARE EVERYWHERE 46
  47. WHAT HAVE I DONE 47

  48. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? .  

          ###   #  #  #   #  #      #  #     #  #       .         &&&   &  &  &   &  &      &  &     &  &       48
  49. 2: WHAT IS THE STATE OF COMMUNITY DOCUMENTATION? WHAT ABOUT

    GENDER? ▸ “he”, “his”, “guys” and “dude” 49
  50. 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
  51. 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
  52. 3: HOW CAN WE IMPROVE IT? HOW CAN WE IMPROVE

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

    IT? ▸ ember-cli-addon-docs ▸ retext-assuming ▸ alex (or ember-cli-alex) 53
  54. 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
  55. None
  56. 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 57