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.