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?