The next chapter of my career

Well, folks, the time has come for me to move on.  Today is my last day at Google.

After I eliminated my position, I got to thinking about what I want to do next.  I thought about going back to tech writing, and there was plenty of opportunity to do so at Google, but it didn't draw me in, like it has in the past.  I thought about managing a different type of team, but that didn't resonate with me either.  In short, there was just nothing at Google that called my name.

I'm a firm believer in choosing work that you can be passionate about.  We spend so much of our time at work.  Our job should be something that gets us out of bed in the morning with anticipation for the day to come.  Sure, not every day can be like that, but overall, we should be doing something we love.

I also believe that careers don't have to be linear.  For some, the right choice is to work in one place for a long time, becoming a deep expert in what they do, and climbing the ladder over time.  Others prefer to hop from startup to startup, engaging in the excitement of a new venture.  Still others prefer to contract, sometimes working 80 hours a week on an exciting job, and other times taking long vacations. Many of us encounter a combination of those situations over the course of our career.

Finally, I see skills as abstract entities that can be applied to the same job title, or can be repurposed for new and different roles.  I think that outlook will become increasingly necessary as personnel needs morph to accomodate an ever-more-quickly changing world.

So.  What's next for me?

I'm going to start my own company, helping organizations implement collaborative developer documentation.

The industry's changing.  We've seen it.  I've talked about it a bit in this blog, but here it is: Developers no longer go to the manual first when they get stuck.  They go to Google, and type in the problem or error code they're encountering.  More often than not, this leads them to a forum, a blog, or some other "non-official" resource.

"Official" documentation is still important.  Without an initial version of the docs that accompanies the API distribution, and explains how to set up the SDK, how to use the APIs, and gives some sample code, it would be impossible for developers to understand what the API is, and what it's meant to do.  That documentation can never be written by the community, because writing it requires close collaboration with the developers who created the API.

However, there's a long tail of documentation that is best written by the community.  For example: explanations of how to overcome obscure errors that occur only in certain environments, sample code that shows how to use the API for things it's very good at, but for which it wasn't intended to be used, and, sometimes, up to date translations of the official docs.

For one thing, this kind of information is best learned through trial and error by a large user base.  Even if a tech writer did nothing but use the APIs, she would never encounter errors that occur with a different development environment, software version combination, or operating system.  The community is working on a diverse set of environments, will encounter these errors, and can help each other overcome them.

Secondly, more people means more viewpoints, and more viewpoints can provide better documentation. The whole is greater than the sum of its parts.  A community of collaborators provides creativity and strategic thinking that can only come from the meeting of more than one mind.

There are already many tools that enable collaborative documentation, such as Mindtouch, MediaWiki, and SharePoint, among others.  However, these tools fall short of encouraging people to contribute their knowledge to the docs.  There's no incentive for them to do so.  I have some ideas for fixing that problem.

Another roadblock with collaborative docs is that the review process becomes a bottleneck.  It is not sustainable to have a single person, or even a few people, review all contributions.  I have some ideas for fixing that problem too.

So there you go: that's what excites me.  That's what pulls me out of bed in the morning, eager to find out what the new day holds.  And so, with a mixture of anticipation and sadness, I say goodbye to Google, and welcome the next chapter in my career.

Think through your career.  Does its flow resonate with you?  Are there threads that have resurfaced at various points in your career? What do you like best about what you're doing now?  What haven't you done yet that you hope to do in your lifetime?

The Potential of Forums

I've spent the last couple of weeks recovering from a tonsillectomy.  Having your tonsils taken out when you're pushing 40 sounds (and is) insane.  Surprisingly, though, there are a fair number of people who do it.  When I stumbled across a forum of people my age undergoing the same surgery at the same time, I was happily surprised.

The official documentation that my hospital and doctor provided was helpful.  It told me what kind of surgery I'd be having done, the expected prognosis and recovery time, and detailed the medications I could take.  However, as with any documentation, it was missing a lot.  What the official docs were missing, the forum provided. Forums are the perfect complement to documentation. 

2 things that forums are great at

In general, forums are great for two things.  First, they're a good medium for people in similar situations to share practical advice with one another.  I'm thankful to the person who discovered that chewing Dentyne Ice gum helps with ear pain after surgery, and am very glad that person thought to share his discovery.  That kind of information would never have been included in my doctor's documentation, but it's nonetheless very helpful.

Forums also provide emotional support.  Just knowing that someone else is grappling with the same thing; whether that be going through a medical procedure, or trying to write code against the same libraries, is heartening.  Your peers for whatever's at hand are uniquely able to appreciate your triumphs and empathize with the problems you're facing.

2 things that would make forums even better

Forums would be even better if the information that goes into them were easier to get out.  They work well for people who are facing the same problem at the same time and can have a real-time conversation about it.  But once that conversation is archived, it's harder for Joe Schmoe to come along a few weeks later and get all the learnings that the first people figured out together.  The same learning process is often just repeated over and over with new people.  Search should be improved for forums so that people can learn from past conversations, as well as current conversations. Even better would be the addition of artificial intelligence to forums, so that forum conversation about documented topics could automatically be added to the relevant documentation.  That would bring the best worlds of documentation and forums together; a perfect marriage.

The second thing that would make forums better would be a way for participants to create a  reputation based on their contributions, at their discretion.  This reputation should be persistent across forums of similar nature; for example, a developer's Java reputation and her Android reputation should combine to show her skills as an Android app developer.  Stack Overflow has a good algorithm for reputations; it would be great if we could extend that to other sites. 

How do you use forums?  What works about them, and how could they be better?

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.