Slide 1

Slide 1 text

Hello!

Slide 2

Slide 2 text

My name is Lucas Mazza.

Slide 3

Slide 3 text

@lucasmazza on Twitter & GitHub

Slide 4

Slide 4 text

I’m from São Paulo, Brazil.

Slide 5

Slide 5 text

No content

Slide 6

Slide 6 text

We <3 OpenSource

Slide 7

Slide 7 text

Documentation for fun and profit let’s talk about

Slide 8

Slide 8 text

Documentation? seriously?

Slide 9

Slide 9 text

why

Slide 10

Slide 10 text

Documentation is about communication.

Slide 11

Slide 11 text

Documentation never forgets.

Slide 12

Slide 12 text

Documentation helps you.

Slide 13

Slide 13 text

Documentation helps your team.

Slide 14

Slide 14 text

Documentation helps the new guy.

Slide 15

Slide 15 text

code documentation 1

Slide 16

Slide 16 text

“Just read the source” they say...

Slide 17

Slide 17 text

but code can be:

Slide 18

Slide 18 text

but code can be: 1. messy

Slide 19

Slide 19 text

but code can be: 1. messy 2. too decoupled

Slide 20

Slide 20 text

but code can be: 1. messy 2. too decoupled 3. dynamic

Slide 21

Slide 21 text

but code can be: 1. messy 2. too decoupled 3. dynamic 4. all the above

Slide 22

Slide 22 text

Documentation can provide a proper abstraction for your API

Slide 23

Slide 23 text

And nobody gives a crap until they need it.

Slide 24

Slide 24 text

def parse(header) directives = {} header.delete(' ').split(',').each do |part| next if part.empty? name, value = part.split('=', 2) directives[name.downcase] = (value || true) unless name.empty? end directives end

Slide 25

Slide 25 text

def parse(header) directives = {} header.delete(' ').split(',').each do |part| next if part.empty? name, value = part.split('=', 2) directives[name.downcase] = (value || true) unless name.empty? end directives end # Internal: Parses the Cache Control string to a Hash. # Existing whitespace will be removed and the string is split on commas. # For each part everything before a '=' will be treated as the key # and the exceeding will be treated as the value. If only the key is # present then the assigned value will default to true. # # Examples: # parse("max-age=600") # # => { "max-age" => "600" } # # parse("max-age") # # => { "max-age" => true } # # Returns a Hash.

Slide 26

Slide 26 text

So, document those hashes and splat arguments. # Document possible combinations def where(*every_possible_thing_ever) # ... end # What options it accepts? # What values are default? def where(stuff = {}) # ... end

Slide 27

Slide 27 text

And maybe those bang methods too. # It mutates the object... def merge! # ... end # ...or raises an error? def save! # ... end

Slide 28

Slide 28 text

Or suggest alternative implementations. # This is an internal method called every time Devise needs # to send a notification/mail. This can be overridden if you # need to customize the e-mail delivery logic. For instance, # if you are using a queue to deliver e-mails... def send_devise_notification(notification, opts={}) # ... end

Slide 29

Slide 29 text

Choose your weapon: (but it isn’t that important) 1. RDoc 2. YARD 3. Rocco 4. Tomdoc 5. Plain text / markdown

Slide 30

Slide 30 text

Not just your precious Ruby code

Slide 31

Slide 31 text

Not just your precious Ruby code 1. CLIs and shell scripts

Slide 32

Slide 32 text

Not just your precious Ruby code 1. CLIs and shell scripts 2. That truckload of JavaScript

Slide 33

Slide 33 text

Not just your precious Ruby code 1. CLIs and shell scripts 2. That truckload of JavaScript 3. CSS modules and styleguides

Slide 34

Slide 34 text

Not just your precious Ruby code 1. CLIs and shell scripts 2. That truckload of JavaScript 3. CSS modules and styleguides 4. and so on...

Slide 35

Slide 35 text

Document what you think that needs documentation

Slide 36

Slide 36 text

Rails has documentation for the public API

Slide 37

Slide 37 text

Mongoid has docs for pretty much everything

Slide 38

Slide 38 text

Bootstrap only has usage guides

Slide 39

Slide 39 text

usage documentation 2

Slide 40

Slide 40 text

How do I use [insert project name] on my app?

Slide 41

Slide 41 text

Step 1 - start with a nice README https://github.com/lostisland/faraday

Slide 42

Slide 42 text

Step 1.1 - maybe a website too http://warpspire.com/kss/

Slide 43

Slide 43 text

Step 1.1 - maybe a website too http://documentup.com / http://devise.plataformatec.com.br

Slide 44

Slide 44 text

Step 2 - community guides http://emberjs.com/guides/

Slide 45

Slide 45 text

Step 2 - community guides http://guides.rubyonrails.org

Slide 46

Slide 46 text

it should be easy to contribute to your documentation.

Slide 47

Slide 47 text

otherwise nobody will contribute.

Slide 48

Slide 48 text

GitHub wikis are awesome for this.

Slide 49

Slide 49 text

Guides, posts and plugins https://github.com/plataformatec/simple_form/wiki

Slide 50

Slide 50 text

Troubleshooting and help https://github.com/sstephenson/rbenv/wiki

Slide 51

Slide 51 text

GitHub wikis might end up a mess.

Slide 52

Slide 52 text

Devise wiki: 95 pages, 83 How-to’s.

Slide 53

Slide 53 text

Content can get outdated easily. Isn’t easy to fix that.

Slide 54

Slide 54 text

Examples with extra dependencies: HAML / Slim, RSpec, SimpleForm / Formtastic, etc.

Slide 55

Slide 55 text

(btw, @dkastner is awesome) A lot of room for improvement

Slide 56

Slide 56 text

By community, for the community. • Keep it simple. • Help keeping it up to date. • Spread the word.

Slide 57

Slide 57 text

process documentation 3

Slide 58

Slide 58 text

Companies can be creative

Slide 59

Slide 59 text

Crazy setups and tools

Slide 60

Slide 60 text

• SSH tunneling black magic. • Windows VMs. (yes, windows VMs) • Outdated/undocumented tools. • Permissions bureaucracy.

Slide 61

Slide 61 text

Document it like it was open source. (Or enough to help new developers join the project)

Slide 62

Slide 62 text

A tale of two markdowns

Slide 63

Slide 63 text

Most Frequent Asked Question Ever:

Slide 64

Slide 64 text

is this feature bugfix user story done?

Slide 65

Slide 65 text

can I test this feature user story bugfix ?

Slide 66

Slide 66 text

No one knows.

Slide 67

Slide 67 text

CHANGELOG.md features and bugfixes that landed on the mainline

Slide 68

Slide 68 text

CHANGELOG.md just like an open source project

Slide 69

Slide 69 text

# Changelog ## Unreleased * [Bug #50] Fixed missing Devise translations ## 03-10-2013 * [User Story #200] New signup landing page * [Bug #49] Fixed broken links on 'About us' ## 03-07-2013 -2 * [User Story #199] OAuth2 support * [User Story #198] Deliver a welcome email to new users * Ruby version upgraded to 2.0.0-p1 :heart: ## 03-07-2013 * Security release, updated dependency XPTO.

Slide 70

Slide 70 text

A few days and some changes later...

Slide 71

Slide 71 text

DEPLOYMENT TIME!

Slide 72

Slide 72 text

No content

Slide 73

Slide 73 text

1. Migrate the database

Slide 74

Slide 74 text

1. Migrate the database 2. Setup a redis instance

Slide 75

Slide 75 text

1. Migrate the database 2. Setup a redis instance 3. A bazillion of rake tasks

Slide 76

Slide 76 text

1. Migrate the database 2. Setup a redis instance 3. A bazillion of rake tasks 4. ?????????

Slide 77

Slide 77 text

1. Migrate the database 2. Setup a redis instance 3. A bazillion of rake tasks 4. ????????? 5. PROFIT

Slide 78

Slide 78 text

http://www.flickr.com/photos/gnislew/1453056073/

Slide 79

Slide 79 text

PRODUCTION.md what needs to be done on the next deploy

Slide 80

Slide 80 text

PRODUCTION.md because sometimes “cap deploy” isn’t enough

Slide 81

Slide 81 text

PRODUCTION.md devops will love you

Slide 82

Slide 82 text

# Deployment tasks ## Unreleased 1. Regenerate the app config YML with the ‘config:setup’ task 2. Run `rake data:import` to seed new data ## 01-18-2013 (v1.5.0) 1. Update API configuration for new endpoint ## 12-15-2012 (v1.4.0) 1. Install imagemagick on worker machines

Slide 83

Slide 83 text

visibility and communication.

Slide 84

Slide 84 text

managers, stakeholders, qa analysts, devops, newcomers...

Slide 85

Slide 85 text

You can paste it anywhere and it won’t look programmer-ish.

Slide 86

Slide 86 text

It helped us a LOT.

Slide 87

Slide 87 text

it might help you.

Slide 88

Slide 88 text

food for thought

Slide 89

Slide 89 text

Documentation is about communication.

Slide 90

Slide 90 text

Documentation isn’t a one man job. (Rails Guides has almost 300 contributors)

Slide 91

Slide 91 text

Friends don't make friends reconstruct the entire callstack on their brains.

Slide 92

Slide 92 text

Friends help friends to document the collective code.

Slide 93

Slide 93 text

No content

Slide 94

Slide 94 text

No content

Slide 95

Slide 95 text

No content

Slide 96

Slide 96 text

No content

Slide 97

Slide 97 text

No content

Slide 98

Slide 98 text

Thanks.