[Cabal] FAQ and support.pidgin.im

[Luke Schierer]

On Tue, Oct 31, 2006 at 10:48:15AM -0500, Ethan Blanton wrote:
> Luke Schierer spake unto us the following wisdom:
> > Let me know what you all think.  Is there something better I should be
> > looking at?  Does the lack of good auth prove to be an unacceptable
> > flaw?
> 
> So, I missed almost this entire FAQ thread due to hardware failure
> (I've been fighting a dying disk drive for quite some time now; I now
> have a replacement, but it's not behaving either, becauase it's a
> decade newer than the controller it's attached to.), but I have some
> comments.  I'm not sure precisely what has been resolved and what
> hasn't, but here are my opinions on the matter.
> 
> The FAQ should be rendered as one large page, or at the very worst one
> page for each major section.  One page per question is simply too
> painful to *read*, regardless of how nice it might be to edit -- no
> one will ever read our FAQ (even more so than right now).  Regardless
> of the FAQ solution we go with, it needs to be easy for the *user* to
> read, or it won't serve its purpose.  Easy for the developer to edit
> is also a major bonus.

This is a good point, more telling than simply reacting to the color
scheme being "grotesque," which is solvable.  I've reorganized the
nacent faq in the wiki to be a page per section.

This is a hard problem.  NO ONE is going to do a *good* job managing a
flat-file faq, esp. not with the wiki editor.  It is hard enough to do
it in vim.  So a flat file faq means either substantially what we have
now, with substantially just developers editing it, and even that
happening too rarely, or we accept some level of displaying the faq in
multiple pages, or we do not use a wiki.

> 
> I'm not convinced that "easy for the user to edit" is a good idea -- I
> think this means we'll have to spend a lot of time babysitting the
> FAQ, honstly.  Think of all the users who come in with some obscure
> problem (Gaim doesn't compile because I have a hand-built merge of gtk
> 2.8.1 and gtk 2.10.3 that plays my themes just how I like ...) and
> then say "that should be in the FAQ".  An *important* feature of a FAQ
> is that the Qs really are FA.  If that is not the case, you run into
> the same problem as the previous paragraph, and users just won't
> bother to read it.  Also, most users are horribly illiterate, and it
> reflects poorly upon *us* when our FAQ is mangled pseudo-English.

Honestly, if we restrict this to registered users, I think it will
require a managable level of moderation.  That is, managable IF the
ticketing system actually gets used and does not itself need significant
babysitting the way our nearly unused SF trackers do.  If trac's tickets
get used, get responded to, get closed when solved, get addressed
instead of ignored, then I'll have the free time to do FAQish things.

> 
> That said, I'm willing to give an open wiki FAQ a try, and possibly be
> proved wrong.  (Other FAQs I'm aware of on the web seem to support my
> position, but...)

I've found some helpful docs in wiki support setups.  That's far more
than I can say of forums, which are, in my opinion, either agressively
moderated or entirely useless.

> 
> I don't know jack about so-called "web programming", but if one of us
> does, maybe we could write a FAQ parser and frontend that does more or
> less the same thing as the current sf.net FAQ (reads some textish
> files and compiles them), but with a data format that doesn't suck.
> It shouldn't be too hard, for example, to come up with some semi-sane
> way of putting each entry (or each section) in its own file and tying
> them together.  Or whatever Luke's requirements are, as he largely
> manages the FAQ.

I've done some of it.  I could write faq stuff myself, I just hesitate
to do so, because its just as easy to make mistakes in "web programming"
as it is in real programming.  Being the only user of something makes
the odds of discovering a bug only when it hits hard high.  I also have
no experience using anything other than .htpasswd auth, and that makes
me even more reluctant to take this on.

luke

> 
> Ethan
> 
> -- 
> The laws that forbid the carrying of arms are laws [that have no remedy
> for evils].  They disarm only those who are neither inclined nor
> determined to commit crimes.
> 		-- Cesare Beccaria, "On Crimes and Punishments", 1764



> _______________________________________________
> Cabal mailing list
> Cabal at pidgin.im
> http://pidgin.im/cgi-bin/mailman/listinfo/cabal