Conversation and Community, by Anne Gentle

I just started reading Conversation and Community by the amazing Anne Gentle. I'm a few dozen pages in, and already recognize that I'm sitting at the feet of a guru.

I've been doing documentation for 15 years, roughly, making it up as I go along. I've done pretty well, considering, with 8 or 12 books (depending on what you count), and large portions of the Apache httpd docs to my credit, but Anne has made a science of it, and I've been continually impressed with the way that she wrangles groups of people into producing great content in literally a few days.

I'll have to write more, later, once I've finished the book. I find that books like this tend to clarify and focus things that I've observed, but never taken the time to really analyze, about documentation and "customer support".

Open Help Conference this weekend

This weekend I'll be speaking at the Open Help Conference in Cincinnati about writing a better manual. I've given this talk before at various places, but this time it's completely rewritten and reorganized, so I hope a few of you might turn out for this. There will also be other great content on the 14th and 15th, and on the 16th - 18th there will be team documentation sprints.

Open Help Conference, 2013

This weekend I attended the OpenHelp Conference in Cincinnati. Unfortunately, I was only able to go to one day of it, as we had to be back for something Sunday morning.

It was smallish, and so there was a lot of good conversation and brainstorming.

The focus was both documentation and support, which are, of course, deeply intertwingled. It gave me a lot to think about, and I really wish I could have been there for the second day as well.

Siobhan McKeown, from the Wordpress documentation team, was at the conference, and took amazing notes, so I'm going to link to her writeup for each talk.

The day started with Jorge Castro talking about using StackExchange to handle the Question & Answer part of support.StackExchange is part of the StackOverflow family of sites, Each StackExchange site is focused on a particular community, and is very focused on Question and Answer format, rather than general discussion. It allows users to vote for the quality of questions and answers, and seems to be a great way to get the subject matter experts more directly involved in the support process.

Siobhan's notes are here.

Following that, Michael Verdi, from the Firefox support team, talked about the SuMo site and the work that they had done to help users find the answers to their question. Of particular interest was some graphs he showed of the improvement in customer satisfaction, as well as the rate of answered questions, brought about by just improving the search functionality, to help users find the right docs so that they didn't even need to ask their question.

Firefox has their own home-grown, but Open Source, solution, called Kitsune. It has some StackExchage-like features, and also has a great tool called Army of Awesome, which is a way to watch Twitter mentions of your project/product, and ensure that at least one person from the expert community has responded to each one.

Here's Siobhan's notes.

This was followed by a panel discussion including Jorge, Michael, Jeremy Garcia (LinuxQuestions.org, and Siko Bouterse from Wikipedia. The discussion ranged from Wikipedia author retention to further discussion of many of the issues that Michael and Jorge had raised.

I spoke next, talking about listening to your audience. This is something I've thought a lot about over the years. My trepidation in speaking at this conference was that it seems like many of the people there know a lot more about documentation and support than I do, as I'm largely self-taught in this area. But it seemed that my remarks were well received. Once again here's Siobhan's notes, which in this case are way better than my own notes for my talk.

I was the last speaker of the day, and this was followed by a general discussion of the things that had been raised during the day, as well as many related issues.

You can see a lot of commentary about the events of the day, and of Sunday, by looking at the #openhelp keyword on Twitter. I'm looking forward to reading Siobhan's notes from Sunday's sessions.

Apache HTTP Server PDF documentation

Although I've known for a while that it was possible to build the HTTP Server docs as PDF, I never really bothered to find out how. Finally this afternoon I was poking around and figured out how. The latest docs are available in PDF format here, and I'll try to keep them somewhat fresh, if you want to bookmark that.

Apache HTTPd 2.0 docs (pdf - 3Mb)
Apache HTTPd 2.2 docs (pdf - 4Mb)
Apache HTTPd 2.3 (trunk) docs (pdf - 4Mb)

Write a better FM

I've been delighted to see the "Write a better FM" meme that's been spreading slowly through various blogs. I understand that I'm to attribute this to Kathy, but I've been saying this for years. It's not sufficient to tell people to Read The Fine Manual, you have to actually listen to the questions that they are asking, and make sure that TFM actually answers them. And, if it doesn't, then make it better.

This is sometimes as easy as it sounds, but usually isn't, for reasons that are often non-obvious to people that are in a place to make the world better.

It's too hard to make the docs better. Those of us who are involved in documentation need to:

  • make it easier for folks to tell us what's broken
  • be less defensive when they suggest ways to fix it
  • clearly identify our audience and listen to their problems
  • provide clear, correct, efficient ways for them to achieve their goals, rather than telling them that they have the wrong goals

If we don't, what happens is that a thousand stinkweeds bloom. I'm discovering this the hard way with mod_rewrite. Because the documentation for mod_rewrite is so intimidating, and folks don't know how to contribute changes to it, instead they write hundreds of HowTos and tutorials and recipes and rants about how to do things in mod_rewrite. These articles are, for the most part, wrong. The ones that work, often do so by sheer chance, and are prone to break if attempted elsewhere. But desperate users take these tutorials, hack on them until they mostly work, and they pass their hard-won ignorance on to other folks.

We could have prevented this, but we chose, by our inaction, not to do so. The problem is *much* harder to fix than it would have been to prevent.

I'm thinking about better ways to allow end-users to tell us that the docs suck, or to suggest improvements. I've never been a fan of the PHP methodology, which I have at times called "Scripture With Commentary", primarily because so much of the commentary is crap. However, it gets the job done, and seems to be the best of the bad. I'd love to hear your suggestions of better ways to collect user feedback, and, perhaps more importantly, incorporate it into the end product.




About

Some people are heroes. And some people jot down notes. Sometimes, they're the same person. (The Truth. Terry Pratchett)