Rich Bowen has been documenting open source software since 1999
Who is your audience?
The first thing you need to do is understand who your audience are
- where are they coming from?
- where are they?
You cannot expect your audience to come to you for help. When your documentation is bad they go somewhere else. There are hundreds of website offering horrible help for Apache.
What do they care about? Otherwise they won’t be interested in your answer.
In OS projects we have a habit of not listening to users.
Open Help conference attendees are weird because they care about documentation. This is unusual in the open source community. We need to take advantage of this.
Why do you care about documentation?
- Most developers appear to write docs because they feel that they have to. This makes it easy for people to get involved in a project in writing docs.
- Fame and fortune – you are sorely misguided. However, non-writing development community value people who take the time to do it.
To help people solve actual real world problems that they’re having. It’s great to help someone who is having a real world problem and help them find the answer. Requires patience and empathy.
Who are your audiences?
- Decision makers
- Developers
- End-users
It helps to imagine an actual person who you are writing for. You can anticipate questions.
First phase of documentation – imagine the needs that people have.
“Before you help the old lady across the street, you should find out whether she wants to go.”
Who they’re not:
- your audience is not all young white men who speak English. Often we act like we don’t know this.
- example is needle and haystick in PHP. This doesn’t translate outside of English.
- colloquialisms don’t translate to other languages. It makes people feel like they’re not on the inside – they feel like the “other”.
Decision Makers
- want to know what your product does
- what is it like?
- why is it better than other things?
- This is your elevator pitch so make every word count
- “this is what you can do with your software”
- Tell the decision-maker what it does
Original Text: “Quibberty is an attempt to develop a reference implementation of the QU438 standard which is fast, relaible and bug free and released under the GPL.”
Revised text: “Quibberty moves your mouse pointer as you move your head.”
Pictures are important. A screenshot is more valuable than a paragraph describing a screen, a screencast is more valuable than a page of screenshots.
Testimonials are also valuable.
End-Users
They don’t care how things work, they just want to solve a problem or accomplish a task.
- an example is more valuable than a whole prose description
- a screenshot is worth a thousand words
- a screencast is worth a thousand screencasts
Examples
- Examples should actually work
- Placeholders are okay, but actual valuables are more meaningful. Use actual examples rather than foo/bar
- an example should be correct, fully functional, tested, best-practice, useful, annotated
A major part of documentation is to help people not feel stupid.
- you should test every single one of your examples. Nothing is more frustrating to a beginner than an example from the official docs that doesn’t work.
- try to find an example that actually does something useful. This can be difficult.
- annotate your examples
Developers
Is both easier and harder. There’s a lot of overlap between the three different audiences.
Keep these three audiences in mind but use interlinking
API Docs
- a lot in common with “how do I” docs
- an example of how to call a function can be more useful than a page of discussion
Are your docs working?
Once your initial docs are written you need to determine whether they’re good enough. Start listening to what your users are saying. You have no control over where they go.
- provide an instant feedback mechanism
- respond swiftly
- if your documentation is in a wiki then you have a permanent feedback method but you need to be vigilant against spammers
- analysis of how people got to your docs can be really insightful. Look into search terms. Ask people to update tutorials that rank highly. Contact people who write good documentation and see how you can get them involved
- Docs comment section – are you getting valuable content that way? Even if you have to spend time curating it, if you get 20% good content then it’s worth doing it.
Responding to questions
- stale or unanswered questions are worse than not having feedback at all
- long-answered posts say that you don’t care
- even a “we’re listening” comment and follow through is better, if you don’t that’s worse
Comment systems
- a comment backlog is good for documentation sprints
- good for recruiting new people
- means continual improvement of the docs
Happier users result in more traffic to your docs, rather than to third-party sites.
Larry Wall cited these as qualities of a good open source developer:
- Laziness helps you to write code to solve problems
- impatient makes you optimize your code to work faster
- hubris encourages you to put your code out
These are the opposite of doing customer support:
- Diligence
- Patience
- Humble
After Larry gave the talk people thought they could be lazy, impatient, and hubristic, and there was lots of arrogant people.
The following year his talk said that a community also needs to embrace diligence, patience, and humility.
- Localization – make it easy for people to localise, it’s the gateway drug to your docs team. Check out Pootle
- Talk to the devs – close communication with the devs is essential so you can ask them questions and remember that they appreciate what you do
- Advocacy – you are the liaison to the development team. Sometimes people won’t like what you say.
Mailing lists – people do not use mailing lists. They are a thing of the past. However, it is a valuable resource because its a searchable archive, not as a live resource.
Where else are your users?
Your docs weren’t good enough so they went somewhere else. You need to go where they are.
- Stack Overflow – Today stack overflow is the defacto documentation for your project. The sooner you embrace this the happier you’ll be. If you don’t participate then you have to be content with the advice that people are getting. Apache made the mistake of not getting participating in the community to begin with.
- Your docs can’t be what stack overflow is – your docs cannot cover every possible scenario. That would be cluttered and confusing. Most of the content there isn’t appropriate.
- Answer questions on SE and whenever possible link back to your official docs. Update docs if key concepts aren’t covered.
- IRC – people want immediate answers but often don’t get them. “Answering a question well, once, and then linking to it, trumps answering it quickly a thousand times.” Either answer the same question again and again, imperfectly, or write well-thought out answers and then linking to them. An IRC bot is valuable. It can provide answers to questions.
- IRC is also a good way to identify people who know a lot and should be brought back into the community. Pay attention to people who answer a lot of questions, even if they’re not always write. Identifying passion is critical. Recruit everyone you find there.
- It has its own culture and is often not pretty. Patience is a great way to get people involved. Don’t start by assuming that someone is an imbecile.
Mentoring is an investment that reaps a lot of dividends. Identify the next generation of the community and invite them to participate.
- Facebook, Google Plus, and Twitter – your project is on social media. You should get involved with those conversations. People get into rants on Twitter and they are disarmed by personal responses to public rants.
- Youtube – people post screencasts. Establishing a presence on youtube is a great asset to your community
- Weird third-party forums - we hate these sites because they are outside the community and they’re doing it for ad revenue. They are full of bad advice. But it’s where the audience is. What do you do with these?
- you could go an participate in these. You could serve them with a cease and desist (which hardly ever works). This is what Apache did with askapache.com. Rather than being nice to him and trying to negotiate they sent a cease and desist. Now they can’t even talk to them.
- Google Alert – daily notifications of mentions of your project/product. Lots of occasional noise but there could be occasional gem.
What does your audience care about?
- Solving actual problems. They don’t care about the backstory or the technical details. Remember that there’s 98% of the problem that they can’t see. Don’t make an assumption that this is the first stop, they may have looked for help elsewhere.
- your job is to solve their problem. Point them towards the best solution, not merely the fastest or easiest.
- Have well-written recipes to send them to.
- Always try to understand what they’re trying to accomplish. Why are they doing something the way that they’re doing it?
- Don’t assume that they are stupid
Reasons for doing stupid things:
- my boss told me to
- we have a contract
- legal reasons that I can’t discuss
- interactions with other things that they don’t have time to go into
Don’t invalidate all of the time that people have put into something.
Remember:
- you, too are an idiot
- you were a beginner not so long ago
- that they are way better than you at something.
They should ask smart questions - but you are responsible for how you response to that. If your response is rude, go find another hobby.
