Popularity of writing the manuals?

Recently we had a few discussions on the FLOSS Manuals list about how to increase the quality of documentation for an open source project, and noted that quantity does not always increase quality. And someone noted that bad doc is worse than no doc at all! Naturally, I found parallels between the open source documentation world and the world of enterprise software.

Andy Oram started the discussion by sharing an essay positing that documentation will always be a cost, asking “Why is it more of a struggle for a project to provide information than to provide software?”  He asserts that any attempt to be comprehensive with documentation only results in overwhelming the budget, especially when video and in-person training are involved. I was reminded of Michael Hughes’ UX Matters post, Surviving Tough Times as a User Assistance Writer. He says, “We need to write less, and we need to write better stuff.”

Now, one counter question to Andy’s theory about bridging the training gap is this fact: training and education do not always come from manuals. So, in the case of an open source project’s documentation, does FLOSS Manuals align itself with the “support” mechanism of running software, or the “marketing/attention” mechanisms of getting software to be used?

In one case of a FLOSS Manuals user, Bill, he said he never can get people to read the documentation. He always ends up supporting people one-on-one with real-time communications. It sounds like Bill is the support department for his open source software project. Yet he could free up his own time by having killer doc that supports his users. I don’t think education necessarily aligns with “support,” though. Just because your users know how to use the software doesn’t mean they won’t run into the occasional bug or get stuck on a problem they can’t solve by themselves.

Here’s an example – I was talking to a guy who runs a WordPress consulting business with probably a dozen clients. He LOVES WordPress.tv because if a client has a problem, he points them directly to a link with a video that tells them what to do to solve their problem. He’s still the central support mechanism though. The difference is that he didn’t have to create the content that helps his clients.

I think that with the introduction of community and earlier feedback in our documentation, doc becomes more “fun” and rewarding. I have much more fun writing entries for my blog than I do for the everyday doc that I write for my day job. Part of the “fun” is that the blog gives me more feedback – comments from readers, and blog stats I can see every day that show me that people really are reading what I write, plus I can see what they searched for.

What is converging is the idea that all these sources of documentation – lists, FAQs, tutorials, wikis, and so on – could live in and be maintained by one “community” or even a single hired hand. I say it in my book, and I’ll say it again, we are living in an amazing time where the audience and user is more accessible than ever through these tools that amplify conversations and connections.


  • July 28, 2009 - 8:12 am | Permalink


    Nice post. I think FLOSS Manuals aligns itself with both “the “support” mechanism of running software” AND “the “marketing/attention” mechanisms of getting software […] used”

    ..AND education, and a lot more.

    But just to switch to what Andy is saying…What Andy is proposing is very interesting as he has talked a lot in other posts about getting tools to help people write less, and better. Notably he advocates ‘FAQ scraping’ tools etc to help find out what the target audience is trying to find out. This is also similar to your points about audience feedback via blogs etc…

    Having tools like this to better refine what to write is always going to be useful, however retrospectively scraping questions and divining the scope of a manual/documentation/support materials from what you find is not always going lead you to where you want to go. If you think of a class of students – who asks the most questions? its not the kid at the back who is struggling with the content, its the smart student at the front that likes to impress the teacher…(I think exactly this scenario can be very true of forums in open source development projects, but the illustration I use is a general comment on problems of retroactively scraping forum questions etc)

    So I would like to suggest that the audience you want to reach is not always the same as those asking the questions…


  • July 29, 2009 - 10:25 am | Permalink

    Oh, great point Adam. It takes much more analysis to figure out what people are not asking but need to know. People are going to be better at that than a tool.

  • Leave a Reply