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
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "General" mailing list
http://lists.osafoundation.org/mailman/listinfo/general
