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?
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
47. U C B A
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