User Love and how to get it

User Love and how to get it through good Documentation

Facts and Stories

Story

LMMS original documentation

LMMS original documentation What was wrong?

What was wrong?

LMMS original documentation What was wrong? Barely any content

What was wrong?

Barely any content

LMMS original documentation What was wrong? Barely any content Description of the trivial

What was wrong?

Barely any content

Description of the trivial

LMMS original documentation What was wrong? Barely any content Description of the trivial Loosely coupled

What was wrong?

Barely any content

Description of the trivial

Loosely coupled

Ask the Developers

Ask the Developers Fix the bugs

Fix the bugs

Ask the Developers Fix the bugs Add more features

Fix the bugs

Add more features

Ask the Developers Fix the bugs Add more features Update the documentation!!!!

Fix the bugs

Add more features

Update the documentation!!!!

Developer problems

Developer problems Users asking stupid questions

Users asking stupid questions

Developer problems Users asking stupid questions Fixing bugs more important

Users asking stupid questions

Fixing bugs more important

Developer problems Users asking stupid questions Fixing bugs more important One developer

Users asking stupid questions

Fixing bugs more important

One developer

LMMS – the self help guide My decision: write the documentation

My decision: write the documentation

LMMS – the self help guide My decision: write the documentation I was the one asking stupid questions

My decision: write the documentation

I was the one asking stupid questions

LMMS – the self help guide My decision: write the documentation I was the one asking stupid questions Documentation helps other users learn

My decision: write the documentation

I was the one asking stupid questions

Documentation helps other users learn

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

My decision: write the documentation

I was the one asking stupid questions

Documentation helps other users learn

Learn more about the program

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 Quid pro quo code writing

My decision: write the documentation

I was the one asking stupid questions

Documentation helps other users learn

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 learn for themselves

Developers Love Good Documentation Users can learn for themselves Users can answer other users questions thesheriff : telling a secret - http://flickr.com/photos/thesheriff/194236786/

Users can learn for themselves

Users can answer other users questions

Developers Love Good Documentation Users can learn for themselves Users can answer other users questions Users write their own documentation tizzie : the greatest book - http://flickr.com/photos/tizzie/65362232/

Users can learn for themselves

Users can answer other users questions

Users write their own documentation

Developers Love Good Documentation Users can learn for themselves Users can answer other users questions Users write their own documentation Users go on to be Developers michale : girl power - http://flickr.com/photos/michale/238445168/

Users can learn for themselves

Users can answer other users questions

Users write their own documentation

Users go on to be Developers

Starting the documentation What did I want?

What did I want?

Starting the documentation What did I want? Everything I didn't know

What did I want?

Everything I didn't know

Starting the documentation What did I want? Everything I didn't know: Instrument tutorials

What did I want?

Everything I didn't know:

Instrument tutorials

Starting the documentation What did I want? Everything I didn't know: Instrument tutorials What could automation do

What did I want?

Everything I didn't know:

Instrument tutorials

What could automation do

Starting the documentation What did I want? Everything I didn't know: Instrument tutorials What could automation do Full reference for the controls

What did I want?

Everything I didn't know:

Instrument tutorials

What could automation do

Full reference for the controls

Starting the documentation What did I want? Everything I didn't know: Instrument tutorials What could automation do Full reference for the controls Organised roadmap

What did I want?

Everything I didn't know:

Instrument tutorials

What could automation do

Full reference for the controls

Organised roadmap

Starting the documentation What did other people want?

What did other people want?

Starting the documentation 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 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

Starting the documentation What did we all want?

What did we all want?

Starting the documentation Who is this 'we' anyway?

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/

Novices

Different users Novices Intermediate whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/

Novices

Intermediate

Different users Novices Intermediate Advanced ross : experts only - http://flickr.com/photos/ross/4368015/

Novices

Intermediate

Advanced

Different documentation Novices Tutorials How Tos Quick start guides wiccked : riding a bike - http://flickr.com/photos/wiccked/358029324/

Novices

Tutorials

How Tos

Quick start guides

Different documentation Advanced References API specs Implementation details Black voodoo ross : experts only - http://flickr.com/photos/ross/4368015/

Advanced

References

API specs

Implementation details

Black voodoo

Different documentation Intermediate Subject guides whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/

Intermediate

Subject guides

Different documentation Intermediate Subject guides How to achieve particular tasks using all relevant features of your program whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/

Intermediate

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

Different documentation Intermediate Subject guides What are these “tasks”? whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/

Intermediate

Subject guides What are these “tasks”?

Different documentation Intermediate Subject guides Look for related tools whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/

Intermediate

Subject guides

Look for related tools

Different documentation Intermediate Subject guides Look for related tools Look for related goals whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/

Intermediate

Subject guides

Look for related tools

Look for related goals

Different documentation Intermediate Subject guides Look for related tools Look for related goals “ Tips and Tricks” whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/

Intermediate

Subject guides

Look for related tools

Look for related goals

“ Tips and Tricks”

Different documentation Intermediate Subject guides Look for related tools Look for related goals “ Tips and Tricks” Extensible list whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/

Intermediate

Subject guides

Look for related tools

Look for related goals

“ Tips and Tricks”

Extensible list

Different documentation Intermediate

Intermediate

Different documentation Novices Intermediate Advanced Tutorial Subject guides Reference wnorrix : pre group photo – IndLinux 2005 - http://flickr.com/photos/wnorrix/43845049/

Novices Intermediate Advanced

Tutorial Subject guides Reference

Different documentation Novices Intermediate Advanced How? Why? What? wnorrix : pre group photo – IndLinux 2005 - http://flickr.com/photos/wnorrix/43845049/

Novices Intermediate Advanced

How? Why? What?

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.

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.

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

Plan overall structure

Break modules down into submodules

Eventually get to real module code

Approaches to Programming 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

Write known code for actual features

Make modules that join features together

Integrate modules into overall structure

Approaches to Programming Top down Bottom up Both at the same time Plan overall structure Write code for either top or bottom levels Modules and features meet in the middle

Top down

Bottom up

Both at the same time

Plan overall structure

Write code for either top or bottom levels

Modules and features meet in the middle

Approaches to Documentation Both at the same time Plan overall structure Divide up chapters into sections or Write sections Documentation meets in the middle

Both at the same time

Plan overall structure

Divide up chapters into sections or

Write sections

Documentation meets in the middle

Approaches to Documentation Both at the same time Plan overall structure – Table of Contents Introduction Tutorials Subject Guides References Appendices

Both at the same time

Plan overall structure – Table of Contents

Introduction

Tutorials

Subject Guides

References

Appendices

Approaches to Documentation Both at the same time Plan overall structure – Table of Contents Introduction Requirements, Installation, Terms and Conventions Tutorials Subject Guides References Appendices Glossary, Key Shortcuts, License, Roadmap, ...

Both at the same time

Plan overall structure – Table of Contents

Introduction

Requirements, Installation, Terms and Conventions

Tutorials

Subject Guides

References

Appendices

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

Approaches to Documentation Both at the same time Write!

Both at the same time

Write!

Approaches to Documentation Both at the same time Write! Start with what you know

Both at the same time

Write!

Start with what you know

Approaches to Documentation Both at the same time Write! Start with what you know Write in small increments

Both at the same time

Write!

Start with what you know

Write in small increments

Approaches to Documentation Both at the same time Write! Start with what you know Write in small increments Reward yourself for good work

Both at the same time

Write!

Start with what you know

Write in small increments

Reward yourself for good work

Approaches to Documentation Both at the same time Write! Start with what you know Write in small increments Reward yourself for good work Save favourite sections for writers' block

Both at the same time

Write!

Start with what you know

Write in small increments

Reward yourself for good work

Save favourite sections for writers' block

Approaches to Documentation Both at the same time Write! Be consistent

Both at the same time

Write!

Be consistent

Approaches to Documentation Both at the same time Write! Be consistent Glossary / Terms and Conventions

Both at the same time

Write!

Be consistent

Glossary / Terms and Conventions

Approaches to Documentation Both at the same time Write! Be consistent Glossary / Terms and Conventions Layout and formatting

Both at the same time

Write!

Be consistent

Glossary / Terms and Conventions

Layout and formatting

Approaches to Documentation Both at the same time Write! Be consistent Glossary / Terms and Conventions Layout and formatting Don't be afraid to rewrite

Both at the same time

Write!

Be consistent

Glossary / Terms and Conventions

Layout and formatting

Don't be afraid to rewrite

LMMS Documentation examples

LMMS Documentation examples

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/

Simple editing from anywhere

Documenting on a Wiki Simple editing from anywhere Cross-referencing jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/

Simple editing from anywhere

Cross-referencing

Documenting on a Wiki Simple editing from anywhere Cross-referencing Revision view and control jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/

Simple editing from anywhere

Cross-referencing

Revision view and control

Documenting on a Wiki Simple editing from anywhere Cross-referencing Revision view and control Collaboration – many editors jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/

Simple editing from anywhere

Cross-referencing

Revision view and control

Collaboration – many editors

Documenting on a Wiki Simple editing from anywhere Cross-referencing Revision view and control Collaboration – many editors Googleable jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/

Simple editing from anywhere

Cross-referencing

Revision view and control

Collaboration – many editors

Googleable

What you want from a Wiki jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/

What you want from a Wiki [[ComplexLink Link to a complex page]] jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/

[[ComplexLink Link to a complex page]]

What you want from a Wiki [[ComplexLink Link to a complex page]] [[http://example.com/images/splash.png]] jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/

[[ComplexLink Link to a complex page]]

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

What you want from a Wiki [[ComplexLink Link to a complex page]] [[http://example.com/images/splash.png]] http://example.com/wiki/ComplexPage jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/

[[ComplexLink Link to a complex page]]

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

http://example.com/wiki/ComplexPage

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 jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/

[[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

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 LADSPA jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/ [1]

[[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

LADSPA

Fact 6 Style matters og2t : scotland with style – http://flickr.com/photos/og2t/89821504/

Writing Style

Writing style Clean Concise Precise Literate Correct

Clean

Concise

Precise

Literate

Correct

Writing style Clean Visually simple and appealing Not distracting Concise Precise Literate Correct

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

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

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

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

Clean

Concise

Precise

Literate

Correct

Must accurately reflect state of program

Kept up to date

Get the facts Users love good documentation

Users love good documentation

Get the facts Users love good documentation Developers love good documentation

Users love good documentation

Developers love good documentation

Get the facts Users love good documentation Developers love good documentation Different documentation for different users

Users love good documentation

Developers love good documentation

Different documentation for different users

Get the facts Users love good documentation Developers love good documentation Different documentation for different users Documentation isn't hard to write

Users love good documentation

Developers love good documentation

Different documentation for different users

Documentation isn't hard to write

Get the facts Users love good documentation Developers love good documentation Different documentation for different users Documentation isn't hard to write Use a wiki

Users love good documentation

Developers love good documentation

Different documentation for different users

Documentation isn't hard to write

Use a wiki

Get the facts Users love good documentation Developers love good documentation Different documentation for different users Documentation isn't hard to write Use a wiki Style matters

Users love good documentation

Developers love good documentation

Different documentation for different users

Documentation isn't hard to write

Use a wiki

Style matters

Do you have time?

Do you have time? I don't have time to write a test!

I don't have time to write a test!

Do you have time? I don't have time to write a test! I don't have time to add a ticket!

I don't have time to write a test!

I don't have time to add a ticket!

Do you have time? I don't have time to write a test! I don't have time to add a ticket! I don't have time to write documentation!

I don't have time to write a test!

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