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
   

   View Slide

2. Documentation is
   WIN
   or
   WTFM*
   Dana Jones
   Developer Evangelist
   Spree Commerce, Inc.
   * Hat tip to @briandq
   

   View Slide

3. The Problem
   ●
   More customers
   ●
   More OSS contributors
   ●
   Support is expensive
   ●
   Historical record
   ●
   Code and UI are not always self-explanatory
   Twitter: @danabrit
   

   View Slide

4. The Solution?
   ●
   More salespeople?
   ●
   More recruitment?
   ●
   More support engineers?
   ●
   Github version history?
   ●
   Improve the UI and the code?
   Twitter: @danabrit
   

   View Slide

5. Yes!
   Twitter: @danabrit
   

   View Slide

6. Yes!
   But that's not enough.
   Twitter: @danabrit
   

   View Slide

7. You have to write
   the friggin'
   manual.
   Twitter: @danabrit
   

   View Slide

8. The Case Against
   Documentation
   Twitter: @danabrit
   

   View Slide

9. The Case Against
   Documentation
   ●
   Hard
   Twitter: @danabrit
   

   View Slide

10. The Case Against
    Documentation
    ●
    Hard
    ●
    Brittle
    Twitter: @danabrit
    

    View Slide

11. The Case Against
    Documentation
    ●
    Hard
    ●
    Brittle
    ●
    Costly to maintain
    Twitter: @danabrit
    

    View Slide

12. The Case Against
    Documentation
    ●
    Hard
    ●
    Brittle
    ●
    Costly to maintain
    ●
    Boring
    Twitter: @danabrit
    

    View Slide

13. The Case Against
    Documentation
    ●
    Hard
    ●
    Brittle
    ●
    Costly to maintain
    ●
    Boring
    ●
    Time consuming
    Twitter: @danabrit
    

    View Slide

14. So Why Do Them?
    Twitter: @danabrit
    

    View Slide

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
    

    View Slide

16. I'm in.
    Now, what?
    Twitter: @danabrit
    

    View Slide

17. Good documentation – like
    good code – requires
    consistency, craftsmanship,
    and attention to detail.
    Twitter: @danabrit
    

    View Slide

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
    

    View Slide

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
    

    View Slide

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
    

    View Slide