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

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