This document provides tips for improving documentation by letting go of ego and focusing on helping customers succeed. It suggests: 1) Writing documentation with a better voice and scope to meet different user levels from apprentice to master. 2) Defining the document scope to know when objectives are met and avoid scope creep. 3) Avoiding rude responses by remembering users were once beginners and questions lack full context. 4) Listening to understand customers' situations rather than criticizing questions. Frequently asked questions indicate needed improvements. 5) Continually learning to stay connected with customer needs as a project and questions evolve over time.

1. How to let go of your ego
and help your customers
succeed
Subtitle: Don't be a jerk
Rich Bowen - rbowen@geek.net
Community Growth Hacker, SourceForge
@rbowen

3. Open Source = Middle School
Make fun of the new kid
Say mean things to the girls
Show off your scars

4. It's even codified:

5. Smart Questions: Eric Raymond
RTFM and STFW: How To Tell You've Seriously Screwed
Up
There is an ancient and hallowed tradition: if you get a
reply that reads “RTFM”, the person who sent it thinks
you should have Read The F***ing Manual. He or she is
almost certainly right. Go read it.
RTFM has a younger relative. If you get a reply that reads
“STFW”, the person who sent it thinks you should have
Searched The F*ing Web. He or she is almost certainly
right. Go search it. (The milder version of this is when
you are told “Google is your friend!”)

6. Why do we do this?
This is a hobby. Support is a job
People are mean and entitled
The answers are obvious

7. Users vs Customers
What difference does it make?

10. Users, right?
They didn't pay for it
We don't owe them anything

11. Customers
Without them, there's no reason for
your product
Your product is not unique
Good customer service is what
distinguishes you

12. What's the difference
between users and
customers?
The attitude of the
people on the other
end of that transaction.

13. The way you
treat them
defines their
role

14. Disclaimer: PHP are the
good guys
Great documentation
Usually a courteous
customer support
experience
Good parties

15. But ...
The first graders learn by watching us

16. I learned it from *you*

17. So, what can we do ...

18. 1. Write A Better FM
Kathy Sierra

19. ドキュメント
Your audience is not
composed entirely
of white, English-
speaking males
Idiomatic language
is cute, but can also
be very confusing

20. A wonderful example, but requires
idiomatic English to understand

22. Voice
Determine who your audience is
Speak to them

23. Who is your audience?
Apprentice
Avoid terms like "newbie" and "user",
as they set the wrong voice.
Journeyman
Master

24. Apprentice
How to get started
May not know what questions to ask
Preserve their dignity (See also: Don't
be a jerk)

25. Journeyman
Viz: Wikipedia
May do this every day, but it's probably
not their primary skill
Will likely know what to ask, and has
already done some research
Generally wants to solve a problem or
complete a task

26. Master
Doesn't want to waste your time or
theirs
May be a good candidate for project
participation

27. Speak to them
Imagine an actual audience that you're
writing to
This helps set your voice correctly
Good docs will have different voices for
each audience

28. Elevator
“If you can't explain
it simply, you don't
cszar, on Flickr
understand it well
enough”
-Albert Einstein

29. Again, half as long

30. 2: Define
document
scope

31. Scope
What are we going to talk about?

32. Scope
If you don't define your scope, your
readers will insist that you expand it.

33. Benefits
of
defining
your
scope:

34. Benefits of defining scope
You know when you hit it
You know when you're done
You know when you can safely say
"that's documented over there"

35. Document your scope
"This documentation covers ..."
Helpful when people insist you cover
more
Can politely point to your policy

36. This is not just being lazy
Do your thing really well
Let other people do their thing well
This is what the <a> tag is for

37. 3.
Don't
be a
jerk

38. zazzle.com
Co
ro
co lla
st ry:
yo B
u ad
cu m
st an
om n
er ser
s

39. Good Manners
http://www.cyh.com/HealthTopics/HealthTopicDetailsKids.aspx?p=335&id=2526&np=287

40. Being Rude
Most of the time, you don't mean to
That guy was just an idiot
Idiots are frustrating
I've already answered that question
17,000,000 times today

41. Idiots

42. Two things to remember
You were a first-grader once, too
You don't actually know the context of
their question

43. ftp://rbowen:glio124@s.ms.uky.edu/

44. You have a story like
that too. You don't
have to share it with
the whole class, but
we all know you do.

45. Be an advocate, not an ...
Not everything is "good" vs "bad"
There are many right answers
http://www.perl.com/pub/2000/12/
advocacy.html

46. 3.5 - Be a mentor
It takes time
Most people won't thank you
The benefits are immeasurable and will
outlast your "real" work

48. 4. Listen to the
customer

49. Context
Context can be the difference
between a stupid question and a
brilliant one. Don't assume that
the customer is an imbecile.

50. Stupid Questions

51. Yes, some questions are stupid
Attempt to understand the
situation the question came
from, rather than critiquing the
question
They're probably not intentionally
wasting your time

52. Don't hesitate to
suggest a better
solution
But ... they may
have a reason
for their
proposed
solution

53. Frequently Asked Questions
They're called that for a reason

54. Frequently Asked Questions
Don't say "RTFM"
Rather, provide a link directly to the
answer in the FM, so that next time,
they look there first
Actually read that answer, and if it's
inadequate, GO FIX IT

55. Frequently Asked Questions
Also, don't say "STFW"
It's insulting to assume that they
haven't done anything at all towards a
solution.
(Even if it's occasionally true.)
By listening, you can ascertain what
they've already done

56. Yes, people should do
their research, but ...
Being rude as your initial stance is
hugely arrogant
"How to ask smart questions" is an
arrogant document that puts all the
blame on the customer

57. Do it once, really really well
It's better to answer the question once,
really well, and then link to it, than to
answer it repeatedly, getting more
frustrated each time

58. Also, it's a business model

59. Where do docs come from?
These are questions we think users
might want answered
vs.
These are questions customers are
actually asking

60. Young projects
You don't know what folks will ask
You write docs about what you expect
to be useful

61. Mature projects
Listen to the customer, and answer the
questions that they're asking
Frequently asked questions might
actually be feature requests

62. Listening
Mailing lists
Usenet (Yes, it's still alive)
IRC
Third-party websites with their horrible
horrible advice

63. Third-party sites
Sometimes evidence that you've failed
with your docs
Gently point out their errors
Ask them if they'd like to contribute to
the official docs
Everybody wins

64. Third-party sites
Tend to go for fastest cheapest
solution, not necessarily best practice

65. Unfortunately ...
You have to actually participate on
those sites to make a difference

66. Statistics
What docs are people looking at?
What Google search led them there?
Does the doc seem to answer that
question?
Do you provide them a feedback
method?

68. 5. Learn something
If you go very long without learning
anything, you probably are out of touch
with the audience of your
documentation

69. By duane.schoon, Flickr

70. FIN rbowen@geek.net
rbowen@apache.org
sf.net/blog
drbacchus.com
@rbowen
@sourceforge
joind.in/6504