IRC Office Hours, Wednesday, 22 March 2006, 11AM PST

Note: This office hour will take place on the  #chandler channel on freen=
ode. 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>,=20
but maybe the wiki isn't the best methodology for building and maintainin=
g 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 inve=
stments a project makes in
terms of educational payoff. FAQs are highly tuned to the questions users=
 and developers actually
ask=E2=80=94as opposed to the questions you might have expected them to a=
sk=E2=80=94and 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 p=
reference to the official manual,
and it's probably the document in your project most likely to be linked t=
o 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 r=
esponse 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 use=
ful 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 c=
ompleteness, 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 =E2=80=9CFAQ Manager=
=E2=80=9D 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 do=
cuments in a project, whose
content is planned out in advance by the authors, a FAQ is a wholly react=
ive document (see Maintaining
a FAQ). No matter how big it gets, you still never know what the next add=
ition 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 doe=
s not have any obvious
problems like that, there are often unnoticed interdependencies between i=
tems=E2=80=94links that should be
made but aren't=E2=80=94because the related items were added a year apart=
.

The role of a FAQ manager is twofold. First, she maintains the overall qu=
ality 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 mad=
e. Second, she watches
the project mailing lists and other forums for recurring problems or ques=
tions, and to write new FAQ
entries based on this input. This latter task can be quite complex: one m=
ust be able to follow a thread, recognize
the core questions raised in it, post a proposed FAQ entry, incorporate c=
omments 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 =E2=80=
=9CTreat all resources like archives=E2=80=9D in
Chapter 6, Communications); when random people edit the FAQ, they will so=
metimes 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 mainte=
nance. 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 co=
ntribute and edit FAQ items
in a manner similar to a wiki (see the section called =E2=80=9CWikis=E2=80=
=9D in Chapter 3, Technical Infrastructure). I've
seen this happen particularly with Faq-O-Matic (http://faqomatic.sourcefo=
rge.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 nee=
d to to maintain your project's
FAQ, but never let the convenience of the tools seduce you into compromis=
ing 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 "Announce" mailing list
http://lists.osafoundation.org/mailman/listinfo/announce