Tag Archives: documentation

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, 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.

Writing Documentation

Someone (and I now can’t remember who – I think it was Philip Olson) pointed me to Writing Open Source this week, and I’ve been somewhat fixated on it since.

I’ve been writing technical documentation for more than a decade now. 12 years sounds about right. Let’s go with that. I’ve been told I’m good at it, so I keep doing it.

I’ll let you in on a little secret. I don’t tell just anybody this, because they think I’m a freak. I actually enjoy writing documentation. I enjoy figuring out how things work, and then writing about it so that other people don’t have to figure it out. I enjoy catching the first glimmer of the spark of understanding when someone reads what I wrote and gets it for the first time. I love it when people say “Oh! I didn’t realize it was that easy!” and “Why did it seem so complicated before?”

There are precious few places that do documentation well. There’s a number of places where Open Source documentation, and software support in general, typically falls down.

* Tell the user that they’re an idiot, and probably too dumb to use this software. This is done in a variety of ways, and is often abbreviated RTFM, but TFM is often insufficient.
* Pretend that the end-user cares about the architecture of your software. They don’t. They just want to get their job done.
* Fails to distinguish between end-user and developer documentation, and, if there is a distinction, the path from one to the other is left as an exercise to the reader
* Refuses to consider the interrelationship with related technologies, and continually tells the user that “that’s a problem with ProductB” rather than giving them the support that we’re qualified to give.

And many, many others.

As I looked at this website, I became more and more persuaded that perhaps I could help in the effort to write a guide of how to write Open Source documentation – not from the perspective of whether to use passive voice or not, but from the perspective of identifying with your audience and answering the questions that they’re actually asking, not the ones that you feel that they should be asking.

On a related note, during a recent conversation on IRC I suddenly realized that I’ve been working programming jobs all these years because I haven’t been able to find a position that’ll pay me to do what I really love – writing technical docs. I wonder where this realization will take me in coming years.