Documentation is Win - or WTFM

Presented at Windy City Rails 2013 by Dana Jones, courtesy of Spree Commerce, Inc.

Transcript

1. Documentation is WIN Dana Jones Developer Evangelist Spree Commerce, Inc. Twitter: @danabrit
2. Documentation is WIN or WTFM* Dana Jones Developer Evangelist Spree Commerce, Inc. * Hat tip to @briandq
3. The Problem • More customers • More OSS contributors • Support is expensive • Historical record • Code and UI are not always self-explanatory Twitter: @danabrit
4. The Solution? • More salespeople? • More recruitment? • More support engineers? • Github version history? • Improve the UI and the code? Twitter: @danabrit
5. Yes! Twitter: @danabrit
6. Yes! But that's not enough. Twitter: @danabrit
7. You have to write the friggin' manual. Twitter: @danabrit
8. The Case Against Documentation Twitter: @danabrit
9. The Case Against Documentation • Hard Twitter: @danabrit
10. The Case Against Documentation • Hard • Brittle Twitter: @danabrit
11. The Case Against Documentation • Hard • Brittle • Costly to maintain Twitter: @danabrit
12. The Case Against Documentation • Hard • Brittle • Costly to maintain • Boring Twitter: @danabrit
13. The Case Against Documentation • Hard • Brittle • Costly to maintain • Boring • Time consuming Twitter: @danabrit
14. So Why Do Them? Twitter: @danabrit
15. Why is Documentation Win? • Enables code contributions • Accessibility - product easier to understand • Decreases support and training costs • Permanent insight into a transient codebase • Prose explanations ring bells Twitter: @danabrit
16. I'm in. Now, what? Twitter: @danabrit
17. Good documentation – like good code – requires consistency, craftsmanship, and attention to detail. Twitter: @danabrit
18. Documentation Done Right 1.Decide on a set of conventions – naming, markup, capitalization, styles, etc. and stick to them. 2.Do a rough outline. 3.Start writing. 4.Foster a culture of inclusiveness. 5.Prioritize content over style. 6.Get fresh eyes on it often. Twitter: @danabrit
19. Documentation Done Right 7.Use the active voice instead of the passive voice. 8.Links are cheap. Use them. 9.Assume no prior knowledge, or spell out prerequisites. 10.Know your audience – write to their level of technical knowledge. 11.Developer docs: lots of code. User docs: lots of screenshots. Twitter: @danabrit
20. Spree Commerce Docs All Spree Commerce documentation is open source. You can review all Developer, User, API, and Integration guides at: guides.spreecommerce.com We welcome code and documentation contributions from developers at all levels. Twitter: @danabrit