Slide 1
Slide 1 text
How to get people excited about inline docs.
One Inch at a Time
René Föhring // @rrrene inch-ci.org
Slide 2
Slide 2 text
How to get people excited about inline docs.
One Inch at a Time
René Föhring // @rrrene inch-ci.org
Slide 3
Slide 3 text
@rrrene
Slide 4
Slide 4 text
@rrrene
(read in pirate voice)
Slide 5
Slide 5 text
@rrrene
(read in pirate voice)
coder ∙ teacher ∙ researcher
(insert more self-description here)
Slide 6
Slide 6 text
@rrrene
creator of Inch / running Inch CI
Slide 7
Slide 7 text
Inline Docs?
Slide 8
Slide 8 text
# TODO: write some docs
#
def size(filename_or_blob, mode = nil)
end
Slide 9
Slide 9 text
# Returns the size of a given +filename_or_blob+.
#
# size(filename) # => 4096
#
def size(filename_or_blob, mode = nil)
end
Slide 10
Slide 10 text
# Returns the size of a given +filename_or_blob+.
#
# size(filename) # => 4096
#
def size(filename_or_blob, mode = nil)
end
free-form
Slide 11
Slide 11 text
# 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
Slide 12
Slide 12 text
# 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
Slide 13
Slide 13 text
# 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
Slide 14
Slide 14 text
(ง ͠° ͟ل
͜ ͡°)ง
But what is the
problem?
Slide 15
Slide 15 text
„good code is its own documentation“
(myself ten years ago)
versus
„people are not Ruby parsers“
(Zach Holman)
Slide 16
Slide 16 text
Tooling helps!
because, there must be tools, right?
Slide 17
Slide 17 text
No content
Slide 18
Slide 18 text
No content
Slide 19
Slide 19 text
„There are 0 lines of documentation.“
or
„65.7% documented“
Slide 20
Slide 20 text
Look, here are the facts.
Slide 21
Slide 21 text
Designing Inch
Let‘s create a more opinionated tool.
Slide 22
Slide 22 text
First, let‘s make up some rules.
Slide 23
Slide 23 text
it is more important to document …
public methods than private ones
Slide 24
Slide 24 text
it is more important to document …
public methods than private ones
methods with many parameters
Slide 25
Slide 25 text
it is more important to document …
public methods than private ones
methods with many parameters
modules containing methods
Slide 26
Slide 26 text
it is more important to document …
public methods than private ones
methods with many parameters
modules containing methods
...
Slide 27
Slide 27 text
code objects ordered by priority
4
4
4
2
2
0
-1
-2
-2
-4
-5
-7
Slide 28
Slide 28 text
code objects ordered by priority
4
4
4
2
2
0
-1
-2
-2
-4
-5
-7
Slide 29
Slide 29 text
# 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)
Slide 30
Slide 30 text
# Called by the `initech` gem.
#
# @return [void]
def user_registered(username, _)
end
Score: ?
Priority: ?
Slide 31
Slide 31 text
# Called by the `initech` gem.
#
# @return [void]
def user_registered(username, _)
end
Score: 90/100
Priority:
Slide 32
Slide 32 text
# Called by the `initech` gem.
#
# @return [void]
def user_registered(username, _)
end
Score: 90/100
Priority:
Slide 33
Slide 33 text
# Called by the `initech` gem.
#
# @return [void]
def user_registered(username, _)
end
Grade: A
Priority:
Slide 34
Slide 34 text
>> GradeList.all
A – Really good
B – Proper documentation found
C – Please take a look
U – Undocumented (not a bad thing)
Slide 35
Slide 35 text
>> CLI _
Slide 36
Slide 36 text
# 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
Slide 37
Slide 37 text
# 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
Slide 38
Slide 38 text
>> inch suggest
Slide 39
Slide 39 text
>> inch suggest
Slide 40
Slide 40 text
>> inch list
Slide 41
Slide 41 text
>> inch diff
Slide 42
Slide 42 text
>> inch show OBJECT_NAME
Slide 43
Slide 43 text
>> CLI !!!
Slide 44
Slide 44 text
>> CLI !!!
but how to get people excited about this?
Slide 45
Slide 45 text
BADGES
Slide 46
Slide 46 text
No content
Slide 47
Slide 47 text
U
C
B
A
Slide 48
Slide 48 text
No content
Slide 49
Slide 49 text
No content
Slide 50
Slide 50 text
No content
Slide 51
Slide 51 text
No content
Slide 52
Slide 52 text
1500x
Slide 53
Slide 53 text
1500x
Ruby, JS & Elixir
Slide 54
Slide 54 text
The Things I learned
Slide 55
Slide 55 text
#1
Software is about people
Slide 56
Slide 56 text
#2
Be passionate about your ideas
Slide 57
Slide 57 text
#3
Be brave enough to build your own tools
Slide 58
Slide 58 text
#4
Make it useful, accessible and beautiful
Slide 59
Slide 59 text
#5
Share the lessons you‘ve learned
Slide 60
Slide 60 text
How to get people excited about inline docs.
One Inch at a Time
inch-ci.org
René Föhring // @rrrene