Re: Best Practices question

In a message dated: 09 Oct 2002 16:12:30 CDT
Karl Fogel said:

>Paul Lussier <pll@lanminds.com> writes:
>> Is this how it is currently maintained? The reason I ask, is FAQs
>> often suffer from lack of updating, and I've found in the past that
>> tools like FAQ-O-Matic help reduce FAQ-rot :)
>
>I've only had experience with a couple of FAQ-O-Matic-ized FAQ
>documents, so maybe I'm speaking from ignorance, but as far as I can
>tell, It Does Not Work.
>
>FAQs are for humans, and need humans to maintain them. Software can
>assist with this, of course, but FAQ-O-Matic doesn't really address
>the problem of assisting a human maintainer(s). Instead, it tries to
>automate and decentralize maintenance. The results are some pretty
>awful FAQs, filled with redundant, out-of-date, and inconsistent
>information (that's three separate sins, yes, and I've seen them all).
>

Well, I guess, in a sense, I agree with you. However, a tool can
only do the job it's meant for if used properly, right? So what
about a moderated/human maintained FAQ-O-Matic? IOW, only certain
people are allowed to update/change the FAQ-O-Matic data.

>Is FAQ-O-Matic really easier than mailing a patch?

Well, IMO, yes, because:

        - I don't need to worry about all the html crap
          that's in the current FAQ
        - I don't need to search through the file to find where the
          proper FAQ goes
        - There's no redundancy of information
          (Currently each question is in the FAQ twice!)
        - There's no need for anyone to:
                download the svn source
                edit the faq
                create a diff
                mail it in
                wait for it to make it into the main faq

The process could be as simple as mailing the FAQ to the dev list and
someone (I volunteer) can just cut'n'paste it into the FAQ-O-Matic.

In general it doesn't much matter to me if the svn team decides to go
this way or not. I can say I'm much less likely to contribute FAQs
with the current scheme just becaue I find it too tedious.

>Just send to dev@subversion.tigris.org. And the first one can be a
>patch about how to add new FAQ items, yes :-).

I have 3 FAQs I've added to the FAQ, I'll send them in :)

-- 
Seeya,
Paul
--
	It may look like I'm just sitting here doing nothing,
   but I'm really actively waiting for all my problems to go away.
	 If you're not having fun, you're not doing it right!
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org