Documentation is Win - or WTFM

Slide 1

Slide 1 text

Documentation is WIN Dana Jones Developer Evangelist Spree Commerce, Inc. Twitter: @danabrit

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

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

Slide 5

Slide 5 text

Yes! Twitter: @danabrit

Slide 6

Slide 6 text

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

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

The Case Against Documentation Twitter: @danabrit

Slide 9

Slide 9 text

The Case Against Documentation ● Hard Twitter: @danabrit

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

So Why Do Them? Twitter: @danabrit

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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

Slide 19

Slide 19 text

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

Slide 20

Slide 20 text

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