Upgrade to Pro — share decks privately, control downloads, hide ads and more …

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

René Föhring

October 17, 2015
Tweet

More Decks by René Föhring

Other Decks in Programming

Transcript

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

    View full-size slide

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

    View full-size slide

  3. @rrrene
    (read in pirate voice)

    View full-size slide

  4. @rrrene
    (read in pirate voice)
    coder ∙ teacher ∙ researcher
    (insert more self-description here)

    View full-size slide

  5. @rrrene
    creator of Inch / running Inch CI

    View full-size slide

  6. Inline Docs?

    View full-size slide

  7. # TODO: write some docs
    #
    def size(filename_or_blob, mode = nil)
    end

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  10. # 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

    View full-size slide

  11. # 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

    View full-size slide

  12. # 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

    View full-size slide

  13. (ง ͠° ͟ل
    ͜ ͡°)ง
    But what is the
    problem?

    View full-size slide

  14. „good code is its own documentation“
    (myself ten years ago)
    versus
    „people are not Ruby parsers“
    (Zach Holman)

    View full-size slide

  15. Tooling helps!
    because, there must be tools, right?

    View full-size slide

  16. „There are 0 lines of documentation.“
    or
    „65.7% documented“

    View full-size slide

  17. Look, here are the facts.

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  26. # 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)

    View full-size slide

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

    View full-size slide

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

    View full-size slide

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

    View full-size slide

  30. # Called by the `initech` gem.
    #
    # @return [void]
    def user_registered(username, _)
    end
    Grade: A
    Priority:

    View full-size slide

  31. >> GradeList.all
    A – Really good
    B – Proper documentation found
    C – Please take a look
    U – Undocumented (not a bad thing)

    View full-size slide

  32. # 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

    View full-size slide

  33. # 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

    View full-size slide

  34. >> inch suggest

    View full-size slide

  35. >> inch suggest

    View full-size slide

  36. >> inch list

    View full-size slide

  37. >> inch diff

    View full-size slide

  38. >> inch show OBJECT_NAME

    View full-size slide

  39. >> CLI !!!
    but how to get people excited about this?

    View full-size slide

  40. 1500x
    Ruby, JS & Elixir

    View full-size slide

  41. The Things I learned

    View full-size slide

  42. #1
    Software is about people

    View full-size slide

  43. #2
    Be passionate about your ideas

    View full-size slide

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

    View full-size slide

  45. #4
    Make it useful, accessible and beautiful

    View full-size slide

  46. #5
    Share the lessons you‘ve learned

    View full-size slide

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

    View full-size slide