[Announce] IRC Office Hours, Wednesday, 22 March 2006, 11AM PST

[announce at osafoundation.org]

Note: This office hour will take place on the  #chandler channel on freenode. See the wiki page for information on how to join the irc chats.

http://wiki.osafoundation.org/bin/view/Projects/HowToJoinOsafChats


Topic: Chandler product FAQ - How do we build one, what tools do we use?

We're taking a look at our Chandler Product FAQ currently on the wiki at:
 <http://wiki.osafoundation.org/bin/view/Projects/ChandlerProductFAQ>, 
but maybe the wiki isn't the best methodology for building and maintaining a FAQ.

Some background reading:
---------------------------------------------------
Karl Fogel commented on the importance of growing a FAQ:

"Maintaining a FAQ

A FAQ ("Frequently Asked Questions" document) can be one of the best investments a project makes in
terms of educational payoff. FAQs are highly tuned to the questions users and developers actually
ask—as opposed to the questions you might have expected them to ask—and therefore, a wellmaintained
FAQ tends to give those who consult it exactly what they're looking for. The FAQ is often
the first place users look when they encounter a problem, often even in preference to the official manual,
and it's probably the document in your project most likely to be linked to from other sites.
Unfortunately, you cannot make the FAQ at the start of the project. Good FAQs are not written, they are
grown. They are by definition reactive documents, evolving over time in response to people's day-to-day
usage of the software. Since it's impossible to correctly anticipate the questions people will ask, it is impossible
to sit down and write a useful FAQ from scratch.

Therefore, don't waste your time trying to. You may, however, find it useful to set up a mostly blank
FAQ template, so there will be an obvious place for people to contribute questions and answers after the
project is under way. At this stage, the most important property is not completeness, but convenience: if
the FAQ is easy to add to, people will add to it. (Proper FAQ maintenance is a non-trivial and intriguing
problem, and is discussed more in the section called “FAQ Manager” in Chapter 8, Managing Volunteers.)"

 --- Karl Fogel, Producinig Open Source Software, p.26

And he comments on the role of a manager for the FAQs:

"FAQ Manager

FAQ maintenance is a surprisingly difficult problem. Unlike most other documents in a project, whose
content is planned out in advance by the authors, a FAQ is a wholly reactive document (see Maintaining
a FAQ). No matter how big it gets, you still never know what the next addition will be. And because it is
always added to piecemeal, it is very easy for the document as a whole to become incoherent and disorganized,
and even to contain duplicate or semi-duplicate entries. Even when it does not have any obvious
problems like that, there are often unnoticed interdependencies between items—links that should be
made but aren't—because the related items were added a year apart.

The role of a FAQ manager is twofold. First, she maintains the overall quality of the FAQ by staying familiar
with at least the topics of all the questions in it, so that when people add new items that are duplicates
of, or related to, existing items, the appropriate adjustments can be made. Second, she watches
the project mailing lists and other forums for recurring problems or questions, and to write new FAQ
entries based on this input. This latter task can be quite complex: one must be able to follow a thread, recognize
the core questions raised in it, post a proposed FAQ entry, incorporate comments from others
(since it's impossible for the FAQ manager to be an expert in every topic covered by the FAQ), and
sense when the process is finished so the item can at last be added.

The FAQ manager usually also becomes the default expert in FAQ formatting. There are a lot of little
details involved in keeping a FAQ in shape (see the section called “Treat all resources like archives” in
Chapter 6, Communications); when random people edit the FAQ, they will sometimes forget some of
these details. That's okay, as long as the FAQ manager is there to clean up after them.

Various free software is available to help with the process of FAQ maintenance. It's fine to use it, as
long as it doesn't compromise the quality of the FAQ, but beware of over-automation. Some projects try
to fully automate the process of FAQ maintenance, allowing everyone to contribute and edit FAQ items
in a manner similar to a wiki (see the section called “Wikis” in Chapter 3, Technical Infrastructure). I've
seen this happen particularly with Faq-O-Matic (http://faqomatic.sourceforge.net/), though it may be that
the cases I saw were simply abuses that went beyond what Faq-O-Matic was originally intended for. In
any case, while complete decentralization of FAQ maintenance does reduce the workload for the project,
it also results in a poorer FAQ. There's no one person with a broad view of the entire FAQ, no one to notice
when certain items need updating or become obsolete entirely, and no one keeping watch for interdependencies
between items. The result is a FAQ that often fails to provide users what they were look-
ing for, and in the worst cases misleads them. Use whatever tools you need to to maintain your project's
FAQ, but never let the convenience of the tools seduce you into compromising the quality of the FAQ.

See Sean Michael Kerner's article, The FAQs on FAQs, at http://osdir.com/Article1722.phtml, for descriptions
and evaluations of open source FAQ maintenance tools."

--- Karl Fogel, Ibid. p. 143-144

------------
This message was posted via Chandler Version: 0.7alpha2.dev-r9703