Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Documentation is Win - or WTFM

Dana Jones
September 12, 2013

Documentation is Win - or WTFM

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

Dana Jones

September 12, 2013

Transcript

20 slides
  1. The Problem • More customers • More OSS contributors •

    Support is expensive • Historical record • Code and UI are not always self-explanatory Twitter: @danabrit
  2. The Solution? • More salespeople? • More recruitment? • More

    support engineers? • Github version history? • Improve the UI and the code? Twitter: @danabrit
  3. The Case Against Documentation • Hard • Brittle • Costly

    to maintain • Boring Twitter: @danabrit
  4. The Case Against Documentation • Hard • Brittle • Costly

    to maintain • Boring • Time consuming Twitter: @danabrit
  5. 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
  6. 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
  7. 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
  8. 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

More Decks by Dana Jones

Other Decks in Technology