user love and how to get it through good documentation

User Love and how to get it through good Documentation

User Love
and how to get it

User Love
and how to get it
through good
Documentation

Facts
and
Stories

Story

LMMS original documentation


What was wrong?


What was wrong?

Barely any content


What was wrong?

Barely any content

Description of the trivial


What was wrong?

Barely any content

Description of the trivial

Loosely coupled

Ask the Developers

Ask the Developers

Fix the bugs

Ask the Developers

Fix the bugs

Add more features

Ask the Developers

Fix the bugs

Add more features

Update the documentation!!!!

Developer problems

Developer problems

Users asking stupid questions

Developer problems


Fixing bugs more important

Developer problems


Fixing bugs more important

One developer

LMMS the self help guide

My decision: write the documentation



I was the one asking stupid questions




Documentation helps other users learn





Learn more about the program





Learn more about the program

Quid pro quo code writing

Facts

Fact 1:
Users Love
Documentation

Users Love Documentation

cayusa : golden compass - http://flickr.com/photos/cayusa/2061945970/

Fact 1:
Users Love Good
Documentation

Users Love Good Documentation

cayusa : golden compass - http://flickr.com/photos/cayusa/2061945970/

Fact 2:
Developers Love
Good Documentation

Developers Love Good Documentation

Users can learn for themselves

rogimmi : manifestazione- http://flickr.com/photos/rogimmi/2385263392/



Users can answer other users questions

thesheriff : telling a secret - http://flickr.com/photos/thesheriff/194236786/




Users write their own documentation

tizzie : the greatest book - http://flickr.com/photos/tizzie/65362232/




Users write their own documentation

Users go on to be
Developers

michale : girl power - http://flickr.com/photos/michale/238445168/

Starting the documentation

What did I want?


What did I want?

Everything I didn't know


What did I want?

Everything I didn't know:

Instrument tutorials


What did I want?



What could automation do


What did I want?




Full reference for the controls


What did I want?




Full reference for the controls

Organised roadmap


What did other people want?


What did other people want?

Everything they didn't know:

Tutorial on how to make a new song

Detailed look at the ways to use instruments

Full reference for the menus

Ponies and kittens living together


What did we all want?


Who is this 'we' anyway?

Fact 3:
There are different
types of user

futureshape : interesting crowd - http://flickr.com/photos/futureshape/2620528647/

Fact 3a:
There are different
types of
documentation

heliocentric : reading stack - http://flickr.com/photos/heliocentric/528094587/

Different users

Novices

wiccked : riding a bike - http://flickr.com/photos/wiccked/358029324/

Different users

Novices

Intermediate

whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/

Different users

Novices

Intermediate

Advanced

ross : experts only - http://flickr.com/photos/ross/4368015/

Different documentation

Novices

Tutorials

How Tos

Quick
start
guides

wiccked : riding a bike - http://flickr.com/photos/wiccked/358029324/


Advanced

References

API specs

Implementation details

Black voodoo

ross : experts only - http://flickr.com/photos/ross/4368015/


Intermediate

Subject guides



Intermediate

Subject guides

How to achieve particular
tasks using all relevant
features of your program



Intermediate

Subject guides

What are these tasks?



Intermediate

Subject guides

Look for related tools



Intermediate

Subject guides


Look for related goals



Intermediate

Subject guides



Tips and Tricks



Intermediate

Subject guides



Tips and Tricks

Extensible list



Intermediate


NovicesIntermediateAdvanced

TutorialSubject guidesReference

wnorrix : pre group photo IndLinux 2005 - http://flickr.com/photos/wnorrix/43845049/


NovicesIntermediateAdvanced

How?Why?What?

wnorrix : pre group photo IndLinux 2005 - http://flickr.com/photos/wnorrix/43845049/

Fact 4:
Good Documentation
is not hard to write

dey : serious child http://flickr.com/photos/dey/69542427/

Writing Documentation

It was a dark and stormy night; the rain fell in torrents except at occasional intervals, when it was checked by a violent gust of wind which swept up the streets (for it is in London that our scene lies), rattling along the housetops, and fiercely agitating the scanty flame of the lamps that struggled against the darkness.

Writing Documentation

Far out in the uncharted backwaters of the unfashionable end of the western spiral arm of the Galaxy lies a small unregarded yellow sun.

Documentation is
just another project

How do you
normally
write code?

Approaches to Programming

Top down

Plan overall structure

Break modules down into submodules

Eventually get to real module code


Top down

Bottom up

Write known code for actual features

Make modules that join features together

Integrate modules into overall structure


Top down

Bottom up

Both at the same time


Write code for either top or bottom levels

Modules and features meet in the middle

Approaches to Documentation



Divide up chapters into sections
or

Write sections

Documentation meets in the middle



Plan overall structure Table of Contents

Introduction

Tutorials

Subject Guides

References

Appendices



Plan overall structure Table of Contents

Introduction

Requirements, Installation, Terms and Conventions

Tutorials

Subject Guides

References

Appendices

Glossary, Key Shortcuts, License, Roadmap, ...



Write!



Write!

Start with what you know



Write!


Write in small increments



Write!



Reward yourself for good work



Write!



Reward yourself for good work

Save favourite sections for writers' block



Write!

Be consistent



Write!

Be consistent

Glossary / Terms and Conventions



Write!

Be consistent


Layout and formatting



Write!

Be consistent


Layout and formatting

Don't be afraid to rewrite

LMMS Documentation examples



Fact 5:
Only one tool...

chazferret : framing hammer collection - http://flickr.com/photos/chazferret/2658412857/

Fact 5:
Use a Wiki

chazferret : framing hammer collection - http://flickr.com/photos/chazferret/2658412857/

Documenting on a Wiki

Simple editing from anywhere

jdlasica : wiki wiki http://flickr.com/photos/jdlasica/413488042/



Cross-referencing




Cross-referencing

Revision view and control




Cross-referencing


Collaboration many editors




Cross-referencing


Collaboration many editors

Googleable


What you want from a Wiki



[[ComplexLink Link to a complex page]]




[[http://example.com/images/splash.png]]





http://example.com/wiki/ComplexPage






http://example.com/wiki/en/0.3/Contents






http://example.com/wiki/en/0.3/Contents

LADSPA


[1]

Fact 6
Style matters

og2t : scotland with style http://flickr.com/photos/og2t/89821504/

Writing Style

Writing style

Clean

Concise

Precise

Literate

Correct

Writing style

Clean

Visually simple and appealing

Not distracting

Concise

Precise

Literate

Correct

Writing style

Clean

Concise

Say no more than you need to

Look for simpler ways of expressing yourself

Precise

Literate

Correct

Writing style

Clean

Concise

Precise

Unambiguous and consistent

Distinguish between similar concepts / terms

Literate

Correct

Writing style

Clean

Concise

Precise

Literate

Spelling, punctuation, grammar

Easy to read

Correct

Writing style

Clean

Concise

Precise

Literate

Correct

Must accurately reflect state of program

Kept up to date

Get the facts

Users love good documentation

Get the facts


Developers love good documentation

Get the facts



Different documentation for different users

Get the facts




Documentation isn't hard to write

Get the facts





Use a wiki

Get the facts





Use a wiki

Style matters

Do you have time?

Do you have time?

I don't have time to write a test!

Do you have time?


I don't have time to add a ticket!

Do you have time?


I don't have time to add a ticket!

I don't have time to write documentation!

Yes! You have time!

Yes! You have time!

Write good documentation!

Questions?

http://lmms.sourceforge.net

Click to edit the title

Click to edit the outline text format

Second Outline Level

Third Outline Level

Fourth Outline Level

Fifth Outline Level

Sixth Outline Level

Seventh Outline Level

Eighth Outline Level

Ninth Outline Level

LCA 2009


Click to edit the title text format

Click to edit the outline text format

Second Outline Level

Third Outline Level

Fourth Outline Level

Fifth Outline Level

Sixth Outline Level

Seventh Outline Level

Eighth Outline Level

Ninth Outline Level

LCA 2009


user love and how to get it through good documentation

Technology