Unfortunately, I had to leave early on the second day, which seems to be when the dust settled and some real work got done. But we had some great discussions on day one. Others have recapped most of our discussions well, but one thing they haven’t talked about is our discussions about mentoring.

I’ve spent the last eight years trying to build and foster a community of documentation writers, most of whom are not professionals. So I’m particularly interested in how the marketing team can mentor new team members who, like me, don’t really know anything about marketing.

My one contribution was a lesson I’ve learned over the years: Give new contributors achievable and concrete tasks. If you tell them to pick something and do it, they usually won’t.

Stormy, Denise, and I continued this conversation at the bar on Tuesday night. One of my big questions was “What do people need to learn?” If you have no background on something, it might not just be the answers you’re lacking; you might not even know what questions to ask. Not only do I not know things about marketing. I don’t know what I don’t know about marketing.

Stormy and Denise rattled a dozen things off, most of which I’ve already forgotten. (There’s a reason I carry a notebook everywhere. I don’t know why I didn’t take it to the bar.)

So how do we pass knowledge like this along? Sure, we could braindump into a wiki. And somebody who’s skilled at content organization could turn it from a braindump into something useful. But it’s actually really hard to write down everything you know about a subject. The good nuggets of wisdom are things you don’t think to mention until the right situation arises. Real life experience matters.

I’m curious what others have found helpful in bringing new contributors up to speed. This isn’t marketing-specific. It happens in any community where many members aren’t professionally trained in what they’re doing. (And I realize I’m asking about those very good nuggets of wisdom about community mentoring that you don’t think to mention.)

This is particularly interesting to me, and not just because I happen to be on that list. (Or, at least, one Shaun McGance is.) It’s interesting to me because we discussed recognition programs during the recent Gnome marketing hackfest. (And, by the way, a big thanks to Google and Novell for their sponsorship.) I was generally supportive of the idea, though wary of alienating contributors who don’t get the recognition.

I think Karsten has a valid point, but I don’t want to throw away all individual recognition. I don’t think there’s much point in throwing a parade for our Owens and Federicos. Yes, they rock. We all know they rock. Putting them on a pedestal doesn’t accomplish anything. The only thing it can do is disenfranchise the people who don’t think they can ever reach that status.

But the story is different for people who haven’t yet made a name for themselves. Two of the people on the list are teammates of mine. They’re relative newcomers, compared to an old fart like me. Giving them public recognition can inspire them to stay on. I’ve seen a lot of contributors come and go. Slowing that revolving door is a win in my book.

Furthermore, I think there’s value in lifting up what we do. A list like this shows interested folks that there are open source people out there who love technical writing. People who strive to provide more than dry stereo instructions. People who are earnestly trying to help users. Then again, maybe calling out vibrant communities of writers would do the same.

Lastly, the fact is that open source rides on the shoulders of individuals. We are not interchangeable parts. In open source, we bring our own ideas and inspirations to the table, and we shape what we do. We wouldn’t be where we are if it weren’t for our rockstars. There are people on that list that I admire. Their work inspires me to be a better writer. And I have no doubt their respective projects would be worse off without them.

Maybe the list would have been less alienating if it had been more personal. List the poeple that inspire you, but don’t pass it off as anything but your personal list of heroes.

So back to the idea of recognizing Gnome contributors, is this doomed to be a well-meaning idea gone wrong? Is there any way to publicly recognize people who have done great work without alienating everybody else?

Comments on the blog please. I’m very interested in what you think.

First, I want to give a short talk on topic-oriented documentation.  This is a very different way of thinking about your documentation, and I’d like to introduce people to it and convey some best practices.  The documentation team went topic-oriented with the new Mallard-based Empathy Help this release cycle.  But topic-oriented isn’t limited to Mallard, nor is it only relevant to user help.  I’ll try to keep the concepts general, while still giving guidance for the real-world systems we use.

After that, I’d like to have about three hours to lead a docfest.  I will help you write or improve any piece of documentation you bring to me.  If you don’t have something in mind already, I’ll find something for you.  It does not have to be user help, and it does not have to be topic-oriented.  I realize this is a hacker’s event, so bring me your API references or developer tutorials.  We’ll turn it from a random collection of thoughts into a coherent document people enjoy reading.

If you’re interested in either, please leave a comment.  Or send me an email at shaunm at gnome dot org.

Here’s the general notion: When the help just isn’t helping you, you’d be able to connect to Live Help, which would be something like a chat room, hopefully populated with people who want to help.  The Live Help chat would be attached to your Yelp window.  Other users would be able to see what document you’re looking at, and send you pages which would open in your Yelp window.

The Live Help channel would also maintain a list of comments made about pages.  So if somebody asks a damn good question, somebody could write something up in a comment on a page of the help document.  As soon as you connect to Live Help, you’d get all the comments stored in the channel for the document you’re viewing.

This is a very rough idea right now.  There are tons of technical and social problems that would have to be solved to make sure it works well.  I’m curious if people have any thoughts, opinions, or criticisms.  (And, by the way, we could totally extend this functionality to developer documentation as well, which I think would be awesome.)

When you’re on a page, the location entry will show you what page you’re on, like so:

You can click the drop-down arrow for a history of where you’ve been:

If you click in the text field, you can type in some search terms:

And when you activate a search, it becomes a location in your history:

It still needs some polish, and I need some icons so I don’t have to abuse the search folder icon.  And it definitely needs some usability testing to see if its functionality is discoverable.  Help viewers can’t afford to have a learning curve.  But it’s been fun to play with so far.

But I think Mallard can substantially help you do this more efficiently.  Mallard takes a very flexible approach to topic-oriented help that allows you to write new content easily.  If you’re writing linear documentation in a format like DocBook, it can be difficult to start writing a solution to a problem without first going through the arduous task of figuring out how it fits into the navigational structure.

If you’re using Mallard, you can just write a stand-alone page and publish it for review.  I recommend first deciding what kind of content you’re writing.  Is it a set of steps to accomplish a task?  A solution to a common problem?  A conceptual overview?  A tip to help the user work smarter?

Mallard doesn’t enforce this content type like DITA does, but knowing what kind of content you’re writing allows you to work from standard templates, which should help you write more useful content.  By the way, I recommend all projects identify common content types and produce templates for them.  This is something we’ll be tackling in the Gnome documentation team soon, and I invite everybody to build on our work.

Once you know what you’re writing, and with template in hand, you can more easily get down to the business of turning thoughts into words.  You can convert your page to HTML without plugging it into a larger document so that your user can review it on its own.

Of course, you’ll still need to get it integrated into a document if you want it to be useful to others.  This isn’t necessarily trivial.  It could be that you can just plug it into an existing guide for common problems.  But you very well may need to rethink parts of your content organization.  Mallard makes content organization easier and more flexible, but there is still no substitute for human thought.

The real boon is that you can help and engage your user before you get bogged down in bookkeeping.  And that helps you create a more dynamic community that can more effectively help its users.

♫NP: Brown Skin by India.Arie

Brad Hards replied to the user, pointing out that KDE documentation is a volunteer effort, and asking the user to contribute something.  I am entirely sympathetic to this response.  I understand the difficulties of trying to produce good help with a skeleton crew of volunteers.  But from the perspective of actually helping the user, it’s a complete fail.  And at the end of the day, we do what we do to help users.

Here is how I think one should respond to a message like this:

1. Sincerely apologize to the user.  Don’t make excuses.  Don’t use volunteerism as an excuse.  If your apology starts with “I’m sorry, but”, you’re doing it wrong.
2. Identify exactly what problems the user is having and how the documentation could have helped the user.  Try to keep an open line of communication with the user.  Do not try to get the user to do work.  Just try to understand his problem better.
3. Write some documentation to help the user.  Don’t worry too much about getting it plugged into whatever documentation system you have.  Don’t worry too much about making it a final copy.  The goal is to have real instructional information that can be reviewed.  Use a wiki or your blog or whatever you find most convenient.
4. Ask the user to review what you’ve written.  You’re not asking the user to be a copy editor or a proofreader.  You’re asking him to tell you if this new documentation is helpful.
5. Revise.  Repeat.
6. When the new documentation works, make sure to put it through whatever quality control systems you have in place and to get it integrated into your documentation system.

Here’s what this accomplishes:  First and foremost, it actually helps the user.  It takes a disgruntled and frustrated user and turns him into a satisfied user.  With this kind of personal attention, it might even turn him into a downright happy user.  Second, because we’ve helped the user by writing real documentation, instead of answering questions on a mailing list, we’re helping countless other users who will never take the time to email us.

Finally, by giving the user something very concrete to do, we’ve given him a low-barrier entry point for contributing to our community.  Maybe he’ll stick around.  Or maybe he’ll go back to whatever he was doing, just a little happier.  I don’t know.  But what I do know is that “Find something to do and do it” is not a good way to get new contributors.  “Here is a simple task that is relevant to you personally” is far more effective.

♫NP: Fred’s Slacks Pt. 1 by Mingo Fishtrap

Since I’ve been on the road, I haven’t had a chance to write much more than 140-character dents.  I need to  get back into the habit of writing daily, so I’m writing about the documentation-related topics that have rattled in my brain for the last 6000 miles.

(Note, if your aggregator strips images, you’re missing half the fun.  Clicky.)

Writing Open Source

Back in June, I attended the first ever Writing Open Source conference.  Thanks to some genorous help from the Gnome Foundation, four members of the Gnome documentation team were able to attend.  Meeting face-to-face in an atmosphere devoted to documentation allowed us to come together as a tightly knit team.  As I said, what’s exciting to me is that I’m not the only person driving things forward, and I really believe that’s due in large part to this event.

It wasn’t just Gnome folks, though.  We met people from various teams and shared our experiences and problems.  There is a lot we can learn from the greater open source documentation community, and a lot we can share with them.  The group has turned into a real community that is undertaking a number of shared initiatives.  If you’re interested in free software and free documentation, please get involved.

Thanks to the conference, I’m now in touch with Jim Campbell of the XFCE documentation team.  And through Jim, I’m in touch with Richard Johnson of the KDE documentation team.  I hope we can get some collaboration brewing.

Mallard

About four years ago, I got the idea in my head that we’re going about documenation in entirely the wrong way.  We write long user manuals that assume users will sit down and read.  That just doesn’t happen.  So I set about doing what any documentation tool developer would do: crafting a system to address the issues I’d encountered.

It took four long years, during which time words like “vaporware” started getting thrown around, but my experiences in those four years helped me turn Mallard from a hare-brained idea into something I believe is a viable documentation platform.  There is now experimental Mallard support in Yelp, and people are banging hard on it.

The feedback so far has been mostly positive, along with some valuable constructive criticism.  I’ve tried very hard to create a system that is easy for writers, translators, and distributors.  As an upstream project that often sees heavy modification by our distributors, we face some fairly unique challenges, and Mallard address some of those challenges in new and innovative ways.

CC

Gnome documentation has traditionally been licensed under the GFDL.  This was certainly a natural choice over a decade ago, but it’s become evident that the GFDL doesn’t suit our needs for various reasons.  This issue has been festering in our community for nearly as long as I have.

With the help of our own beloved almost-a-lawyer Luis Villa, our team has looked at our options and decided to use CC-BY-SA 3.0 for all future work.  Not only does the Creative Commons license suit the needs of our community better, it’s also being adopted by the Ubuntu and Fedora documentation teams, which can help foster collaboration between our communities.  Furthermore, it puts us smack in the middle of an amazing Free Culture movement.

Fun Ahead

There are far more exciting things happening in the Gnome documentation community than I have gimmicky road trip images for.  Paul, Phil, and Milo have been amazing in revitalizing our team.  If you’re interested in documentation, or if you’re looking for a way to get involved with Gnome, or if you just like road trip pictures, join us.  Subscribe to gnome-doc-list or point your IRC client to the #docs channel on irc.gnome.org.

It’s true. I have a hard time letting go. It’s just that, over the last seven or so years, I’ve seen lots of people come and go. Many of those people I thought would become core documentation team people. Some of them could have even replaced me. But inevitably, they all disappear or move on. Maybe it’s my fault. If I were to entrust them with more stuff, they might develop a stronger connection to the team. But I’ve learned to have a strong tendency to keep things close, where I know I can pick up the pieces if people disappear.

But I don’t want to be That Guy that’s blocking everybody. (Insert whatever name you want for That Guy. We all know That Guy in some project or another.) I’ve established the Steering Committee, and I’m trying very hard to empower these guys to be able to kick ass with or without me.

So if anybody catches me being That Guy, please tell me. Our team needs to rock, and it can’t block on me.

♫NP: Bellybone by Robert Bradley’s Blackwater Surprise

This is a huge shift in how we approach, plan, write, and generally work with documentation. The entire community needs to be aware of what’s happening and how it affects them. Fellow hackers, please skip to the bottom for information on how this affects you.

Mallard is a new[1] documentation format that is geared towards topic-oriented help. While you could, in theory, just convert all of your DocBook documentation to Mallard, what you would end up with is a document that is the worst of both worlds. Writing topic-based help requires a new way of thinking about how we present information to our readers.

Mallard is uniquely designed from the ground up to support downstream modification and plugin-based help systems with little to no patching. The dynamic organization structure of Mallard was designed with our help in mind, addressing the challenges we face as an upstream provider.

If you’re interested in writing, editing, reviewing, or otherwise contributing to our documentation, please get in touch with our team. You can email use at gnome-doc-list@gnome.org or join us in the #docs channel on irc.gnome.org. Also, check out our brand new project blog: http://blogs.gnome.org/docs/

We will be holding regular community meetings. Stay tuned for more details.

If you are a maintainer or active developer, know that we are coming for your documentation. It might not be today, but it’s on our radar. If you or someone on your team handles your documentation independently of our team, we still want to be in contact to help them produce better help. Writing is not a one-person task.

We hope that developers will be cooperative with our team as we try to provide them with better help files to make their software better for their users.

We also hope that more people from the greater community, including our downstream communities, will get involved with our team. We are doing some truly exciting things right now, and we’d love to share the excitement.

[1] Yes, I realize I’ve been quacking since 2004. But it’s newly released, and that counts for something.

♫NP: When This Is Over by China Forbes from ‘78