Mallard Helping You Help Users in Need

I recently blogged about how you can help users in need.  My advice was completely independant of what tools you use to write, build, and distribute your help.  Whether you do all your help in a wiki or have static HTML on the web that you keep in a version control system or install DocBook files along with your software, I think what I wrote is a good way to handle user problems.

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

Helping Users in Need

Recently, a user sent an email to the KDE documentation list complaining that the KDE4 documentation left him in the cold after upgrading from KDE3.  This is something the Gnome documentation team needs to be careful with as we think about the Gnome3 help.  We’ll have a lot of Gnome2 users who are disoriented, and it’s our job to help them.

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

Documentation From 6000 Miles

A lot of exciting things have been happening in the Gnome documenation world. One of the most exciting things to me is that much of the excitement is being driven by people other than me. For the last three weeks, my wife and I have been away on the Great American Road Trip. While we were gone, my team continued rocking. I’ve been pleasantly surprised to see people taking ownership, and absolutely delighted to see Mallard uptake.

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

Mammoth

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

Duck

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

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

roadtrip-road1

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.

On Letting Go

There was a point towards the end of the Writing Open Source conference where we were discussing what XML namespace to use for Mallard. And I was totally bikeshedding my own discussion. Emma looked at me and told me I need to let go.

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

Yelp 2.27.1

I’ve just released Yelp 2.27.1, Now With More Ducks. This coincides with gnome-doc-utils 0.17.1, Also Now With More Ducks. This marks the first release with Mallard support built in. And this marks the end of the boring part of the release announcement.

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

Writing Open Source

Last weekend, I attended the first ever Writing Open Source conference. With me were Milo Casagrande, Phil Bull, and Paul Cutler. Those guys have already blogged about the event. You should read what they had to say. Besides the four of us, there were twelve other attendees from various open source documentation teams. It’s amazing how many experiences we have in common.

On the first day, the mayor of Owen Sound came to visit us. She’s going to be participating in the Dancing For Life charity event this weekend. People were trying to get me to give her a waltz lesson, but it’s hard to give a dance lesson without a dance floor. (Plus, waltz is really not my dance.) In retrospect, I probably could have given her a connection lesson.

We all learned a lot. For the last two months or so, I’ve been keeping a notebook about documentation. Basically, it’s a brain dump of things I would tell somebody if I were to sit them down and teach them everything I know about building documentation within a community. After three days, my notebook doubled in size.

I got to show off Pulse and Mallard. Pulse was really well-received. It seems a lot of teams are looking for better ways to track their documentation. I get really excited about Pulse, so it was nice to get others excited as well.

There were a lot of DITA enthusiasts at the conference. Mallard and DITA occupy similar niches: They’re both moving away from DocBook-style books and towards topic-based documentation. The first question (which I expected) after I presented Mallard was along the lines of “Why aren’t you using DITA?”

The obvious advantage of using DITA is that it has a fair amount of industry uptake already. In my defense, I first conceived of Mallard back in 2004. At that time, I hadn’t even heard of DITA, and I don’t think it had nearly the popularity that it now has.

I have been trying to play with DITA since coming back. So far, I’m finding it has a serious lack of hands-on introductory material. As much of a bear as DocBook is, I was able to write my first document after 15 minutes with The Definitive Guide. After two days, I’m still wading through conceptual overviews in DITA.

Mallard is designed to solve a concrete set of problems. DITA can do a lot of things that Mallard can’t, but I’m not at all convinced that I should care about those things. I mean, DocBook can do a lot of things Mallard can’t as well, but after eight years, I’ve learned that most of things just don’t matter to us.

What DITA doesn’t do is what I consider Mallard’s single biggest selling point: dynamic organizational structures. This is critical to our strategy for downstream documentation. It also can produce some nice results for plugin-heavy applications. In fact, one of my primary use cases when designing Mallard was to make something that would work for the GIMP help.

We could probably build dynamic organization on top of DITA, but I’m not convinced it’s worth the effort. Besides capitalizing on uptake elsewhere, I have yet to see any concrete benefits to using DITA. I’m just not sold, and I don’t buy into the notion that I should be automatically sold just because others think it’s cool.

That said, I think we could have reasonably decent two-way conversions between DITA and Mallard. DITA people don’t generally seem to view DITA as a delivery format. So if people want to use DITA as an authoring format and Mallard as a delivery format, I don’t see any reason to put stop energy on that.

So I’ve been trying to learn DITA well enough to make those conversions. Documentation tool chains is what I do, both in Gnome and for a living for the next three days. And I have to say, I haven’t had an easy time of it. And that concerns me particularly because if I have a hard time, I can’t begin to imagine how tortuous it will be to any potential new contributors that come our way.

To their credit, quite a few of the DITA enthusiasts have offered help. They are a friendly bunch. We’ll see how things play out.

♫NP: Bongo Fiesta by Machito & His Afro Cuban Orchestra

Birthday, Camera, Dancing, Action!

Wednesday was my 31st birthday.  Instead of hiding from a tornado like last year, we actually spent the entire day on a movie set for the upcoming independent movie Leading Ladies.  And on Tuesday, our new Nikon D5000 arrived.  (Thanks to all the people who gave advice on the camera.)  What follows is a random collection of thoughts about the movie, interspersed with a random collection of pictures I took.  I wasn’t allowed to take pictures on set, so all the pictures are from the break room and rehearsal room.

My fellow extras waiting
My fellow extras waiting

Being in a movie involves a lot of waiting.  Multiple people have described it to me as “hurry up and wait”.  They’ll tell you to take five and only call you back in half an hour.  Or they’ll put you on set, and you’ll think they’re ready to shoot, and it’ll be ten minutes before they say “Action”.  On the other hand, they’ll sometimes tell you you’ve got an hour, and then be ready for you in fifteen minutes.  It wasn’t annoying or anything.  We were all there for the movie.  Just an interesting observation.

Virginia and Andrew juggle while they wait
Virginia and Andrew juggle while they wait

Benji Schwimmer plays one of the lead roles in the movie.  If you’re into the WCS scene, you probably know who he is.  If not, you might know him from So You Think You Can Dance 2006.  If not, well, you should start dancing.  Benji has an amazing personality.  His enthusiasm is contagious.  Pretty much everybody involved with the movie was very nice.

Dancers practice during a break
Dancers practice during a break
Benji practices whenever and wherever he wants
Benji practices whenever and wherever he wants

Silke and I were dancing some west coast swing in one scene, while most of the crowd was watching Benji and Jordan Frisbee do a routine on stage.  And as glad as I was to get to do some west coast, to be perfectly honest, if I were at a club and Benji and Jordan were doing a routine on stage, I’d be watching.  All the other dancers are Lindy hoppers, so we were the only ones doing west coast.  For all I know, all our parts could end up on the cutting room floor.

Benji and Silke
Benji and Silke

Silke has more pictures up in her Picasa web album.

As an added bit of excitement, on Friday I put in my two weeks notice at Wolfram.  After I’m done at Wolfram, Silke and I are heading on a three-week road trip out West and back again.  And when we return, I’ll be starting something new and exciting.  Very exciting and memorable birthday week.  More details to follow.

Camera Wanted

So I’m looking for a good camera. I’ve got a little Canon Powershot, which I love for day-to-day picture taking. But I want a nice SLR. It’s something I’ve been wanting for a while, but Silke and I are planning a nice vacation in July, and that seems like a good excuse to buy one now.

I’d like the opinions from the peanut gallery.  I know a lot of Gnomers are photonuts.  I do want a decent camera with interchangeable lenses.  But bear in mind that I’m a total n00b, so I want something that’s going to be fairly easy for me to use.  And I don’t want to spend too much.  If the price tag has four digits, it’s too much.

I’ve heard good things about the Canon Rebel.  Thoughts?

Developer Education Programs

There is something that I’ve tossed around in my brain the last couple of days.  It’s not something I really have time to pursue, but I figured a blog post might inspire others.

My employer has an education group.  They travel around and give classes.  This not only helps build a stronger user and developer ecosystem, but it (presumably) is a source of revenue.

So what if Gnome got into the education business?  I don’t think there’s much room for user training (though I may be wrong), but developers are another story.  An education program could generate income for the Foundation (caveat: I have no idea about the legalities of income and non-profits.)  But it’s not just income.  It’s income as a happy side effect of something that can really push our platform.

So there are a number of ways an education program could be approached, and they’re not at all mutually exclusive.  One option is simple training courses.  We’d prepare materials for a certain pre-defined set of classes.  Educators would travel and give on-site courses.  We could probably pursue means of doing remote classes through the tubes.  Courses would be day-long affairs.  Perhaps some would be multi-day, but still short.  Developers would get a cutesy little diploma saying they completed the course.

The training course approach would suit a lot of people.  And it’s probably the least-effort first-start approach.  Another education possibility is a real certification program.  A cutesy little diploma from a single course is a gimmick.  You don’t do it for the diploma; you do it because your employer thinks their employees should get some training.  You don’t put it on your résumé.  A certification program, on the other hand, would involve more extensive study.  It would’t be done in a classroom environment, but we’d need to provide the study materials.  At the end, you need to pass some tests to get an honest-to-goodness certification.  With some good PR, employers might actually care about our certification.

Yet another option is to do education through educators.  I was recently pointed to teachingopensourc.com, a community of educators and enthusiasts who talk about using open source in education.  Perhaps there’s room for our platform in the actual classroom.  One could imagine a class on user interface programming being taught using Gnome.  For that to take off, it would seriously rock to have a textbook, which is a wholly different beast than a tutorial or reference manual.

These are far from fully fleshed-out ideas.  They’re things that I’m very interested in, and are near to my position as “the documentation guy”.  But for them to be anything more than random thoughts on my blog, somebody would have to really drive them home.

Creative Commons Attribution 3.0 United States
This work by Shaun McCance is licensed under a Creative Commons Attribution 3.0 United States.