EuRuKo 2015: One Inch at a Time - How to get People excited about Inline Docs

EuRuKo 2015: One Inch at a Time - How to get People excited about Inline Docs

Faf649a95c7b996e7b7071f85277b3e2?s=128

René Föhring

October 17, 2015
Tweet

Transcript

  1. How to get people excited about inline docs. One Inch

    at a Time René Föhring // @rrrene inch-ci.org
  2. How to get people excited about inline docs. One Inch

    at a Time René Föhring // @rrrene inch-ci.org
  3. @rrrene

  4. @rrrene (read in pirate voice)

  5. @rrrene (read in pirate voice) coder ∙ teacher ∙ researcher

    (insert more self-description here)
  6. @rrrene creator of Inch / running Inch CI

  7. Inline Docs?

  8. # TODO: write some docs # def size(filename_or_blob, mode =

    nil) end
  9. # Returns the size of a given +filename_or_blob+. # #

    size(filename) # => 4096 # def size(filename_or_blob, mode = nil) end
  10. # Returns the size of a given +filename_or_blob+. # #

    size(filename) # => 4096 # def size(filename_or_blob, mode = nil) end free-form
  11. # Detects the size of the blob. # # size(filename)

    # => 4096 # # Params: # +filename_or_blob+:: String filename or blob # +mode+:: Optional mode (defaults to nil) def size(filename_or_blob, mode = nil) end RDoc
  12. # Detects the size of the blob. # # @example

    # size(filename) # => 4096 # # @param filename_or_blob [String] the filename # @param mode [String, nil] optional mode # @return [Fixnum,nil] def size(filename_or_blob, mode = nil) end YARD
  13. # Public: Detects the size of the blob. # #

    filename_or_blob – filename or blob # mode - Optional mode (defaults to nil) # # Examples # # size(filename) # => 4096 # # Returns Fixnum or nil. def size(filename_or_blob, mode = nil) end TomDoc
  14. (ง ͠° ͟ل ͜ ͡°)ง But what is the problem?

  15. „good code is its own documentation“ (myself ten years ago)

    versus „people are not Ruby parsers“ (Zach Holman)
  16. Tooling helps! because, there must be tools, right?

  17. None
  18. None
  19. „There are 0 lines of documentation.“ or „65.7% documented“

  20. Look, here are the facts.

  21. Designing Inch Let‘s create a more opinionated tool.

  22. First, let‘s make up some rules.

  23. it is more important to document … public methods than

    private ones
  24. it is more important to document … public methods than

    private ones methods with many parameters
  25. it is more important to document … public methods than

    private ones methods with many parameters modules containing methods
  26. it is more important to document … public methods than

    private ones methods with many parameters modules containing methods ...
  27. code objects ordered by priority 4 4 4 2 2

    0 -1 -2 -2 -4 -5 -7
  28. code objects ordered by priority 4 4 4 2 2

    0 -1 -2 -2 -4 -5 -7
  29. # These rules provide priorities for all # code objects.

    CODE_OBJECTS = %w( classes modules constants methods parameters ) # ... which are also assigned a score. SCORES = (0..100)
  30. # Called by the `initech` gem. # # @return [void]

    def user_registered(username, _) end Score: ? Priority: ?
  31. # Called by the `initech` gem. # # @return [void]

    def user_registered(username, _) end Score: 90/100 Priority:
  32. # Called by the `initech` gem. # # @return [void]

    def user_registered(username, _) end Score: 90/100 Priority:
  33. # Called by the `initech` gem. # # @return [void]

    def user_registered(username, _) end Grade: A Priority:
  34. >> GradeList.all A – Really good B – Proper documentation

    found C – Please take a look U – Undocumented (not a bad thing)
  35. >> CLI _

  36. # Properly documented, could be improved: ┃ 50 4 Foo#initialize

    ┃ 50 4 Foo::Bar # Please take a look: ┃ 37 4 Foo::API#initialize ┃ 25 2 Foo::CodeObject#initialize # Undocumented: ┃ 0 4 Foo::CLI ┃ 0 4 Foo::API#send_request
  37. # Properly documented, could be improved: ┃ B ↑ Foo#initialize

    ┃ B ↑ Foo::Bar # Please take a look: ┃ C ↑ Foo::API#initialize ┃ C ↗ Foo::CodeObject#initialize # Undocumented: ┃ U ↑ Foo::CLI ┃ U ↑ Foo::API#send_request
  38. >> inch suggest

  39. >> inch suggest

  40. >> inch list

  41. >> inch diff

  42. >> inch show OBJECT_NAME

  43. >> CLI !!!

  44. >> CLI !!! but how to get people excited about

    this?
  45. BADGES

  46. None
  47. U C B A

  48. None
  49. None
  50. None
  51. None
  52. 1500x

  53. 1500x Ruby, JS & Elixir

  54. The Things I learned

  55. #1 Software is about people

  56. #2 Be passionate about your ideas

  57. #3 Be brave enough to build your own tools

  58. #4 Make it useful, accessible and beautiful

  59. #5 Share the lessons you‘ve learned

  60. How to get people excited about inline docs. One Inch

    at a Time inch-ci.org René Föhring // @rrrene