Tweet
Tweet

Slide 1

Slide 1 text

How to get people excited about inline docs. InchJS René Föhring // @rrrene inch-ci.org

Slide 2

Slide 2 text

How to get people excited about inline docs. InchJS 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 @ Neopoly

Slide 6

Slide 6 text

https://www.neopoly.com/jobs/

Slide 7

Slide 7 text

https://www.neopoly.com/jobs/

Slide 8

Slide 8 text

https://www.neopoly.com/jobs/

Slide 9

Slide 9 text

Inline Docs?

Slide 10

Slide 10 text

// TODO: write some docs // function hash(filenameOrBlob, mode = nil) { }

Slide 11

Slide 11 text

// Returns a hash for a given `filenameOrBlob`. // // hash(filename) // => "68ac9064904d853a037a7a8f" function hash(filenameOrBlob, mode) { }

Slide 12

Slide 12 text

// Returns a hash for a given `filenameOrBlob`. // // hash(filename) // => "68ac9064904d853a037a7a8f" function hash(filenameOrBlob, mode) { } free-form

Slide 13

Slide 13 text

/** * Generates a hash for a given `filenameOrBlob`. * * @example * hash(filename) * => "68ac9064904d853a037a7a8f“ * * @param filenameOrBlob [String] the filename * @param mode [String,null] optional mode * @return [String,null] */ function hash(filenameOrBlob, mode) { } JSDoc

Slide 14

Slide 14 text

// Public: Generates a hash for the blob. // // filenameOrBlob – filename or blob // mode - Optional mode (defaults to "SHA1") // // Examples // // size(filename) // => "68ac9064904d853a037a7a8f“ // // Returns String or null. function hash(filenameOrBlob, mode) { } TomDoc

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

„good code is its own documentation“ (based on my early twenties) versus „people are not JavaScript parsers“ (based on Zach Holman)

Slide 17

Slide 17 text

No content

Slide 18

Slide 18 text

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

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 … longer functions than short ones

Slide 24

Slide 24 text

it is more important to document … longer functions than short ones functions with many parameters

Slide 25

Slide 25 text

it is more important to document … longer functions than short ones functions with many parameters modules exporting functions

Slide 26

Slide 26 text

it is more important to document … longer functions than short ones functions with many parameters modules containing functions ...

Slide 27

Slide 27 text

code objects ordered by priority 6 5 4 2 1 0 -1 -2 -3 -4 -5 -7

Slide 28

Slide 28 text

code objects ordered by priority 6 5 4 2 1 0 -1 -2 -3 -4 -5 -7

Slide 29

Slide 29 text

# These rules provide priorities for all # code objects. const codeObjects = [ functions parameters ]; # ... which are also assigned a score. const scores = [0, 100];

Slide 30

Slide 30 text

# Called by the `initech` service. # # @return [undefined] function userRegistered(username, _) { } Score: ? Priority: ?

Slide 31

Slide 31 text

# Called by the `initech` service. # # @return [undefined] function userRegistered(username, _) { } Score: 90/100 Priority:

Slide 32

Slide 32 text

# Called by the `initech` service. # # @return [undefined] function userRegistered(username, _) { } Score: 90/100 Priority:

Slide 33

Slide 33 text

# Called by the `initech` service. # # @return [undefined] function userRegistered(username, _) { } Grade: A Priority:

Slide 34

Slide 34 text

>> require('grade_list').getAll() 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 show OBJECT_NAME

Slide 42

Slide 42 text

>> CLI !!!

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

BADGES

Slide 45

Slide 45 text

No content

Slide 46

Slide 46 text

U C B A

Slide 47

Slide 47 text

No content

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

2100x

Slide 52

Slide 52 text

2100x Ruby, JS & Elixir

Slide 53

Slide 53 text

The Things I learned

Slide 54

Slide 54 text

#1 Software is about people

Slide 55

Slide 55 text

#2 Be passionate about your ideas

Slide 56

Slide 56 text

#3 Be brave enough to build your own tools

Slide 57

Slide 57 text

The End (srsly, please help improving ES6 support)