Documentation for fun and profit

Presented at the NYC.rb Meetup (April 9, 2013)

Transcript

1. Hello!
2. My name is Lucas Mazza.
3. @lucasmazza on Twitter & GitHub
4. I’m from São Paulo, Brazil.
6. We <3 OpenSource
7. Documentation for fun and profit let’s talk about
8. Documentation? seriously?
9. why
10. Documentation is about communication.
11. Documentation never forgets.
12. Documentation helps you.
13. Documentation helps your team.
14. Documentation helps the new guy.
15. code documentation 1
16. “Just read the source” they say...
17. but code can be:
18. but code can be: 1. messy
19. but code can be: 1. messy 2. too decoupled
20. but code can be: 1. messy 2. too decoupled 3. dynamic
21. but code can be: 1. messy 2. too decoupled 3. dynamic 4. all the above
22. Documentation can provide a proper abstraction for your API
23. And nobody gives a crap until they need it.
24. 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
25. 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.
26. 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
27. And maybe those bang methods too. # It mutates the object... def merge! # ... end # ...or raises an error? def save! # ... end
28. 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
29. Choose your weapon: (but it isn’t that important) 1. RDoc 2. YARD 3. Rocco 4. Tomdoc 5. Plain text / markdown
30. Not just your precious Ruby code
31. Not just your precious Ruby code 1. CLIs and shell scripts
32. Not just your precious Ruby code 1. CLIs and shell scripts 2. That truckload of JavaScript
33. Not just your precious Ruby code 1. CLIs and shell scripts 2. That truckload of JavaScript 3. CSS modules and styleguides
34. 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...
35. Document what you think that needs documentation
36. Rails has documentation for the public API
37. Mongoid has docs for pretty much everything
38. Bootstrap only has usage guides
39. usage documentation 2
40. How do I use [insert project name] on my app?
41. Step 1 - start with a nice README https://github.com/lostisland/faraday
42. Step 1.1 - maybe a website too http://warpspire.com/kss/
43. Step 1.1 - maybe a website too http://documentup.com / http://devise.plataformatec.com.br
44. Step 2 - community guides http://emberjs.com/guides/
45. Step 2 - community guides http://guides.rubyonrails.org
46. it should be easy to contribute to your documentation.
47. otherwise nobody will contribute.
48. GitHub wikis are awesome for this.
49. Guides, posts and plugins https://github.com/plataformatec/simple_form/wiki
50. Troubleshooting and help https://github.com/sstephenson/rbenv/wiki
51. GitHub wikis might end up a mess.
52. Devise wiki: 95 pages, 83 How-to’s.
53. Content can get outdated easily. Isn’t easy to fix that.
54. Examples with extra dependencies: HAML / Slim, RSpec, SimpleForm / Formtastic, etc.
55. (btw, @dkastner is awesome) A lot of room for improvement
56. By community, for the community. • Keep it simple. • Help keeping it up to date. • Spread the word.
57. process documentation 3
58. Companies can be creative
59. Crazy setups and tools
60. • SSH tunneling black magic. • Windows VMs. (yes, windows VMs) • Outdated/undocumented tools. • Permissions bureaucracy.
61. Document it like it was open source. (Or enough to help new developers join the project)
62. A tale of two markdowns
63. Most Frequent Asked Question Ever:
64. is this feature bugfix user story done?
65. can I test this feature user story bugfix ?
66. No one knows.
67. CHANGELOG.md features and bugfixes that landed on the mainline
68. CHANGELOG.md just like an open source project
69. # 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.
70. A few days and some changes later...
71. DEPLOYMENT TIME!
73. 1. Migrate the database
74. 1. Migrate the database 2. Setup a redis instance
75. 1. Migrate the database 2. Setup a redis instance 3. A bazillion of rake tasks
76. 1. Migrate the database 2. Setup a redis instance 3. A bazillion of rake tasks 4. ?????????
77. 1. Migrate the database 2. Setup a redis instance 3. A bazillion of rake tasks 4. ????????? 5. PROFIT
78. http://www.flickr.com/photos/gnislew/1453056073/
79. PRODUCTION.md what needs to be done on the next deploy
80. PRODUCTION.md because sometimes “cap deploy” isn’t enough
81. PRODUCTION.md devops will love you
82. # 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
83. visibility and communication.
84. managers, stakeholders, qa analysts, devops, newcomers...
85. You can paste it anywhere and it won’t look programmer-ish.
86. It helped us a LOT.
87. it might help you.
88. food for thought
89. Documentation is about communication.
90. Documentation isn’t a one man job. (Rails Guides has almost 300 contributors)
91. Friends don't make friends reconstruct the entire callstack on their brains.
92. Friends help friends to document the collective code.
98. Thanks.