Soliciting Useful Community Collaboration (or, how to get good community content that isn't interspersed with Viagra ads)

Community collaboration is key, for the reasons I've mentioned in previous posts.  But getting good collaboration isn't straightforward.  You have to architect the site correctly, accommodating the reality of different collaboration types.  You also have to guide the dynamics of a community in order to expose the useful feedback and prevent the entire site from being overrun by trolls, bad information, and Viagra commercials.

There are a couple of different models for encouraging community feedback.

Letting people add notes to the doc

One model is to maintain a canonical, source controlled doc, but let people add notes to the end of each doc page.  php.net is an example of this model can work.  As illustrated by the page I linked to, what makes this work is that contributors post useful information at the end of each page.  The community-contributed content adds to what is already in the documentation, and is helpful to the wider community.

One advantage of this model is that it opens the docs up to collaboration, while ensuring the quality and reliability of  the canonical docs.  This offers protection against trolls, and also against people who have good intentions, but are just wrong.

The disadvantage of this model is that it usually garners a different type of feedback than you'd want. Users generally treat the comments section at the end of a page as either a forum, or as a place to give feedback about the docs.  At best, community feedback generally consists of something like, "I'm trying to do X, please help" or "This page states that this method returns A, but it actually returns B.  Please fix the doc."  At worst, the feedback areas end up being a dumping ground for spammy links to online pharmacies and porn sites.

The way you get around this is to heavily moderate contributed comments, and address and remove those that aren't appropriate.  Over time, the hope is that the docs will get enough appropriate comments that people will use those as an example, and begin to post the kind of thing you're looking for.  Regardless, this will always require some moderation effort.

In my opinion, your best bet with this model is to bypass it altogether.  Instead, link to a dedicated forum where people can garner answers from the community, and link to an issue tracker where people can report issues with the docs.  If that's what people want to do, it's better to just accept it and provide appropriate tools to help.

Letting people modify anything in the doc

A second model is wiki, which opens up the docs entirely to community collaboration.  The community can modify anything at all.  developer.mozilla.org is an example of this model. You can access the collaboration history of each page by selecting "This page -> History" in the upper right hand corner.  The history for the page I linked shows extensive community collaboration.  Wikipedia is another well-known example of this model.

Usually, contributors are required to sign in before they post.  Contributions can be reviewed by a central moderator, or by the community, or both. 

Generally, as a contributor gains more credibility over time, their posts are subject to less oversight.  Often what you end up with is a set of trusted core contributors, who are enthusiastic and familiar with the technology.  You also have a long-tail of one-time or occasional contributors.

I think this model is where the documentation industry is going, and it's generally a good model to adopt.  There are a few things you need to do to make it successful, though.

First and foremost, recognize the value of your top contributors.  Give them some way to earn a public reputation on the site.  Include them in events (either as attendees or speakers), send them t-shirts, give them early access to your APIs.  As Pamela Fox mentioned in her post "How to Alienate a Community 101", though, you have to be careful that you do this in a way that recognizes the spectrum of contributions.  Pamela's post contains good information about how to do that.

Next, adopt a good model for moderating content.  The most sustainable way to do this long-term is to let the community moderate.  Have a voting system, and use votes to flag content that needs to be reviewed.  Allow access level based on reputation, so those users who are most helpful in the forums have the most leeway to modify the docs.  Even if you do these things, though, recognize that you'll still need to put some work into moderating content in the short term.

Mindtouch, and Confluence are a couple of out-of-the-box solutions for this model.  I haven't worked with either one so can't comment on their effectiveness.

Encouraging, and linking to, discussion in a forum

Embrace the fact that much of the useful hands-on discussion occurs in forums. There are several good sites for this, but one of the best sites I know of is Stack Overflow. It is already in wide use, for good reason.  It supports reputations and badges, which makes for a good contributor experience.  It supports tags, which is useful for finding and linking to relevant content. 

If conversation about your product is happening in one of these forums, link to it.  If not, encourage conversation there. 

Speaking to your audience

I've been having trouble getting started on this blog.  There are a lot of things I'd like to talk about here... developer support, API usability, managing a team of writers, and, of course, documentation.  The problem is that I haven't been able to figure out what to talk about first.

It just struck me that the reason for dragging my feet is that I haven't thought about who my audience is.

When you start a new tech writing project, the first thing you do is figure out your audience.  Then you figure out what they're trying to do. Once you know your audience's starting point, and figure out where they're trying to go, you can figure out what you need to do to help them get there.

The challenge with blogs, and with public web documentation in general, is that absolutely anyone can read what you're writing.  If you're reading this right now, you could be a fellow tech writer (either just getting started in your career, or a veteran), a developer, or a tech writing manager.  And those are just the basics.  Heck, you could be a fly fisherman who stumbled across this page accidentally (and is probably wondering why he's still here.)

Web docs have similar challenges, especially those for APIs that are offered freely to the general public.  One developer might be a student, who is trying to piece together an app over cold pizza at 3am because he saw an interesting article about the technology on Slashdot.  Another developer might be writing an enterprise app as part of her day job.  A third developer might be working on an cutting-edge application for that startup he always dreamed about creating. 

One developer might create web apps every day, and know everything that's out there about it.  Someone else might be used to writing drivers in C, but have zero experience with Java.  And yet another person might have no development experience whatsoever; they're trying to get something working by copy-and-pasting sample code and hoping for the best.

How do you write one document that works for everyone?

Believe it or not, it is possible, depending on your definition of "write one document." You can't do it if you expect all of your readers to sit down and read a thousand-page manual from start to finish.  But if you use good navigation and information architecture, and well-configured search, then anyone can find what they need.

The navigation of your docs should work for as many of your typical developers as possible.  People should be able to quickly find the docs that explain what they're trying to do, without having to read through a lot of irrelevant prose.  As a writer, you should think about how to reuse information intelligently.  For example, everyone will need to authenticate their app, so the docs that explain authentication should be linked from lots of places.  On the other hand, only certain apps will need to use particular sequences of methods.

The web is a goldmine of information.  There's no need to explain the basics, such as how REST works.  Find a good resource that explains it, and link to that resource.

But most importantly, just take the time to think about who your audience is.  Being cognizant of who is reading will help guide what you write, even if you just tuck that knowledge away in your subconscious and don't do anything about it.

So back to this blog.  If you're new to tech writing, or new to tech writing management, I hope this blog is helpful to you.  Please feel free to email me with questions and topic requests.  I'll link to additional helpful resources as I find them.  If you're an old pro, or a developer, let's get a conversation going.  Please jump in and argue my points, if you're so inclined! Regardless of who you are, you can navigate the blog by topic or by search.

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.

Evolution of Tech Writing: Where Do We Go From Here?

In the usability studies we've done here at Google, we've found that developers are less and less inclined to read the "official" docs by default.  Rather, their first step is to do a Google search for the information they need.  Often, people turn to forums, blogs, and wikis to figure out how to do what they need to do.  

This fundamentally changes the developer support model. From the point of view of developers, it leverages the brain power of a community of developers who are all trying to accomplish similar objectives, and can learn from one another. 

For an organization offering APIs or developer tools, this enables developers to support one another, which is infinitely more scalable than trying to support all developers from in-house.

For those of us who are involved in developer support, this represents a powerful shift in how we approach our roles.  This is especially true for tech writers.

Tech writers represent the point of view of our developer community.  At the same time, we are internal to the company and have a direct connection to the teams who create the APIs. 

We can use this intermediary position to identify, and then publish, valuable information that developers would have trouble figuring out on their own.  For instance, we are uniquely able to write documentation like:

• A developer's guide for a new API that explains what a library of calls is meant to do, and how to combine the methods in a logical way. 
• Sample code that shows how to approach a particular task in an efficient and sanctioned way.  Bonus points if this sample can be compiled and run, so someone can copy it and use it as the starting point for their own application.
• A reference guide that gives default values and acceptable ranges for arguments, and explains unpredictable side effects of calling a particular method.
• Cross-product documentation that explains how to use one library in conjunction with another.

A tech writer's role is bigger than documentation.  We know what our developers are trying to accomplish, and can advocate on their behalf to make those things easier and more achievable.  We can influence the product teams on all levels, from creating a library of calls that is better architected and easier to understand, to writing APIs that use more understandable signatures.

Tech writers have a unique and irreplaceable role, and always will.   The explosion of information and support now available on the internet helps us capitalize on our unique strengths.  It frees up our time to work on the things that really matter, which makes us more valuable, and makes our jobs much more interesting.  It's a good time to be a tech writer.

Welcome!

Hi!  I’m Jen.  I lead the Developer Documentation team at Google.

My team is part of Google’s Developer Relations team, which helps people use Google’s developer products and APIs.  The tech writers on my team provide proactive support to Google’s developer community.  We collaborate with engineering teams as they create APIs and developer tools, and put ourselves in the shoes of the eventual users.  We think about what works well, and where people might get tripped up.  In some cases, it’s possible to preemptively fix the problematic bits before an external audience ever sees them, in which case we advocate for doing so.  In other cases, we write developer’s guides, tutorials, complete reference documentation, and sample code that help developers do what they set out to do. 

Myself, I’ve been in the tech writing field for about 15 years.  I wrote developer docs for around 12 of those, including for 3 years at Google. I got to the point in my career where I wanted to make an impact in a different way, and gradually transitioned into a management role.  I’ve been here for the last couple of years.

I decided to start a blog as a way to organize what I’ve learned during my tech writing career.  I’ve been fortunate to work with some great mentors and have learned a lot.  Perhaps my blog can serve as a surrogate “mentor” to others.

I hope to garner community participation, feedback, and debate (of the non-snarky variety) on the things I post here, so that I can further learn from the wisdom of the masses. My greatest hope is that the discussion that results from my posts will add more value than the posts themselves.

I would also offer this blog as a resource for answering questions from you, my readers. If you’re facing a particular documentation or management issue and would like to get my advice, and the advice of the community of commenters, please send me email from my Google Profile page.  Note that by doing this you’re implicitly giving me permission to publish the contents of your email. It'd be even better to let the readers of this blog know who you are, too, so unless you’d prefer to remain anonymous, please include a link to a site that tells us more about you.

Although I currently work for Google, the learnings and opinions I express in my posts were garnered from my entire career as a technical writer. No one else necessarily agrees with the opinions I express here. 

Welcome to my blog!  I hope you enjoy your stay here.

Jen

PS Why is this blog called WTFM? Well, we tell our readers to RTFM, so I guess that makes it my job to...