Friday, September 23, 2011

Lots of heads are always better than one

With the advent of web-based docs, users completely gave up the notion of reading an entire 1000-page docset from start to finish.  Here's how it works now:
  • People only read documentation under duress.  If people want light reading, they'll pick up the comics section of the local paper.  If people want to learn how to use an API, they'll find some sample code (probably on a forum somewhere) and try to make it work for their own app.  They won't touch the official docs until they get stuck, and can't easily find the answer to their problem elsewhere.
  • The next thing they'll do is search the official docs for the answer and/or scan the nav bar for something that might help.  If they find something that seems to be relevant, great!  If not, you've already lost them.
  • If the section they navigate to has the answer to their problem, they might be inclined to keep reading.  If not, you've lost them.
  • If they consistently find useful information in the docs, they'll start to trust the docs and will keep coming back to them.  But, as one of my favorite candidates, Doug Anderson, said to me in an interview, "You only get so many opportunities with documentation before you teach people not to look at it."
And that's why it's so hard for a single tech writer to create engaging, satisfying documentation.  There are too many ways it can go wrong.

That's also why the traditional definition of one writer being solely responsible for a thousand-page manual no longer works.  One writer can't scale to support an entire community of diverse developers.  She can't predict all of the different types of code they'll be trying to write, and can't anticipate all the ways they'll get stuck.  So we have to change the way we approach documentation.

One of the most important roles of the official documentation is to introduce libraries, features, and tools for the first time.  When there is no other existing documentation, people will read your docs.  That will always be true.

After people have noodled on your docs for a while, and figured out how to do what they're trying to do, they'll become a strong, capable, worldwide team, skilled at helping specific slices of audiences do exactly what they're trying to do. That's the power of the community.

And that's where our jobs as tech writers change.  We're writing docs, to be sure, but we also need to help the community support itself.  Let people help each other do tasks similar to the work they're doing themselves.  Cultivate a community of helpful developers, and give them easy ways to share their knowledge.  Make sure that helpful pages, responses, and code snippets are surfaced in search results, give pointers to the best ones in the docs, and give credit where credit is due.  Because lots of heads are always better than one.

No comments:

Post a Comment