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
