Documentation is freaking awesome

Slide 1

Slide 1 text

FREAKING AWESOME DOCUMENTATION IS a magical afternoon with Kyle Neath

Slide 2

Slide 2 text

Kyle Neath is...

Slide 3

Slide 3 text

~designer @

Slide 4

Slide 4 text

@kneath

Slide 5

Slide 5 text

warpspire.com

Slide 6

Slide 6 text

A favorite pastime... Building small projects with ruby

Slide 7

Slide 7 text

There’s a library for almost everything

Slide 8

Slide 8 text

It’s not if the library exists... It’s whether I can ﬁgure out how to use the @!&*# thing

Slide 9

Slide 9 text

Documentation is...

Slide 10

Slide 10 text

######################################################################### # # Tags # ######################################################################### # Extract all tags into the tagmap and replace with placeholders. # # data - The raw String data. # # Returns the placeholder'd String data. def extract_tags(data) data.gsub(/(.?)\[\[(.+?)\]\]([^\[]?)/m) do if $1 == "'" && $3 != "'" "[[#{$2}]]#{$3}" elsif $2.include?('][') $& else id = Digest::SHA1.hexdigest($2) @tagmap[id] = $2 "#{$1}#{id}#{$3}" end end end # Process all tags from the tagmap and replace the placeholders with the # final markup. CODE COMMENTS

Slide 11

Slide 11 text

First there was RDoc rdoc.sourceforge.net “latest via CVS”

Slide 12

Slide 12 text

No content

Slide 13

Slide 13 text

No content

Slide 14

Slide 14 text

Then there was YARD yardoc.org

Slide 15

Slide 15 text

No content

Slide 16

Slide 16 text

And of course TomDoc tomdoc.org

Slide 17

Slide 17 text

FACT TomDoc will save the world Photo Credit: Claude Nix

Slide 18

Slide 18 text

Unless you want generated docs Photo Credit: Claude Nix

Slide 19

Slide 19 text

YARD & RDoc are highly structured

Slide 20

Slide 20 text

# Reverses the contents of a String or IO object. # # @param [String, #read] contents the contents to reverse # @return [String] the contents reversed lexically def reverse(contents) ... end

Slide 21

Slide 21 text

TomDoc is lightly structured

Slide 22

Slide 22 text

# Extract all code blocks into the codemap and replace # with placeholders. # # data - The raw String data. # # Returns the placeholder'd String data. def extract_code(data) ... end

Slide 23

Slide 23 text

Also, tools like docco rocco, pycco, shocco

Slide 24

Slide 24 text

No content

Slide 25

Slide 25 text

No content

Slide 26

Slide 26 text

No content

Slide 27

Slide 27 text

Code comments are just the start

Slide 28

Slide 28 text

WEBSITE AN AWESOME

Slide 29

Slide 29 text

Does your project Google?

Slide 30

Slide 30 text

No content

Slide 31

Slide 31 text

What it does

Slide 32

Slide 32 text

Getting Started What it does

Slide 33

Slide 33 text

How to Contribute Getting Started What it does

Slide 34

Slide 34 text

How to Contribute Bug Reports Getting Started What it does

Slide 35

Slide 35 text

How to Contribute Bug Reports More Documentation Getting Started What it does

Slide 36

Slide 36 text

Multiple Versions How to Contribute Bug Reports More Documentation Getting Started What it does

Slide 37

Slide 37 text

(plus, it’s pretty)

Slide 38

Slide 38 text

Great place to post long form tutorials

Slide 39

Slide 39 text

No content

Slide 40

Slide 40 text

README AN AWESOME

Slide 41

Slide 41 text

First Contact

Slide 42

Slide 42 text

Elements of a great README

Slide 43

Slide 43 text

Description Installation Instructions Links to more Docs How to Contribute Credits, Alternatives

Slide 44

Slide 44 text

Think about writing your README ﬁrst (readme driven development)

Slide 45

Slide 45 text

MAN PAGES LOTS AND LOTS OF

Slide 46

Slide 46 text

WTF is a man page? Photo Credit: Tom Preston-Werner

Slide 47

Slide 47 text

Documentation for UNIX tools (command line programs)

Slide 48

Slide 48 text

~$ man rails

Slide 49

Slide 49 text

Many sections ~$ man 5 mustache

Slide 50

Slide 50 text

mustache(5) - Mustache Syntax mustache(1) - Usage of `mustache`

Slide 51

Slide 51 text

BIG CAVEAT gems don’t install man pages :( check out gem-man until then

Slide 52

Slide 52 text

Documentation is...

Slide 53

Slide 53 text

CODE COMMENTS Available with the source Great for Contributors

Slide 54

Slide 54 text

AWESOME WEBSITE Google Juice Command center for docs

Slide 55

Slide 55 text

AWESOME README Available with the source First contact with docs

Slide 56

Slide 56 text

LOTS OF MAN PAGES Available in terminal First place UNIX nerds look

Slide 57

Slide 57 text

A Great Marketing Tool Documentation is...

Slide 58

Slide 58 text

First contact with your project (make it count!)

Slide 59

Slide 59 text

More Docs = Better Perceived Quality

Slide 60

Slide 60 text

More Docs = Easier To Learn

Slide 61

Slide 61 text

More Docs = Easier To Contribute

Slide 62

Slide 62 text

tldr; More People Using Your Project

Slide 63

Slide 63 text

“Top ten reasons why I wont use your open source project” Wynn Netherland pengwynn

Slide 64

Slide 64 text

You don’t have a friggin’ Readme REASON #1

Slide 65

Slide 65 text

You have no project home page REASON #3

Slide 66

Slide 66 text

Documentation is important marketing

Slide 67

Slide 67 text

Therapeutic Documentation is...

Slide 68

Slide 68 text

Forces you to slow down

Slide 69

Slide 69 text

Puts you into a different mindset

Slide 70

Slide 70 text

Forces you to question your code

Slide 71

Slide 71 text

Explaining code often reveals ﬂaws (like an invisible pairing partner)

Slide 72

Slide 72 text

It can also be a great stress reliever sometimes code just sucks

Slide 73

Slide 73 text

Knowing how someone feels about code is valuable # XXX: I hate myself and want to die. # --rtomayko 2010-05-27

Slide 74

Slide 74 text

At the end of the day... Writing documentation produces higher quality code

Slide 75

Slide 75 text

Hacks & Tools Documentation

Slide 76

Slide 76 text

rdoc.info Automatic YARD Generation

Slide 77

Slide 77 text

rdoc.info GitHub Integration (generate docs on push)

Slide 78

Slide 78 text

rdoc.info GitHub Integration (generate docs on push)

Slide 79

Slide 79 text

gem server Locally Generated RDoc

Slide 80

Slide 80 text

railsapi.com Awesome ﬁnd-as-you-type Ruby/Rails/Gem Docs

Slide 81

Slide 81 text

railsapi.com Downloadable Combines Multiple Docs

Slide 82

Slide 82 text

railsapi.com Downloadable Combines Multiple Docs

Slide 83

Slide 83 text

railsapi + Fluid.app Awesome ofﬂine Ruby & Rails documentation

Slide 84

Slide 84 text

jqapi.com Like railsapi.com, but for jQuery

Slide 85

Slide 85 text

ronn Write man pages in markdown github.com/rtomayko/ronn

Slide 86

Slide 86 text

.br \fBronn\fR < \fIfile\fR . .SH "DESCRIPTION" \fBRonn\fR converts textfiles to standard roff\- formatted UNIX manpages or HTML\. ronn\-format(7) is based on markdown(7) but includes additional rules and syntax geared toward authoring manuals\. . man pages are written in roff

Slide 87

Slide 87 text

Slide 88

Slide 88 text

## DESCRIPTION **Ronn** converts textfiles to standard roff- formatted UNIX manpages or HTML. ronn-format(7) is based on markdown(7) but includes additional rules and syntax geared toward authoring manuals. use ronn instead Get HTML generation for free