Re: FAQ

[Telsa Gwynne <hobbit aloss ukuu org uk>]

On Wed, Jun 20, 2001 at 10:29:53AM +0200 or thereabouts, Murray Cumming wrote:
> Gtk-- needs an actively maintained FAQ. Does anyone know of an online
> FAQ system that we can use, or does someone have experience with
> something that we could set up on sourceforge.
> 
> The FAQ system should allow people to add Questions and Answers, and it
> should be able to generate one big FAQ document, preferably in sections.

FAQ-O-Matic: -exactly- what you describe, but for some reason I've
always hated the results and output.

Wiki: anyone can add, and gets very unstructured.

The setup that PHP uses is supposed to be very nice: that involves,
well, a manual and then annotations, I suppose. You can see the
'official' bits and then the comments attached. There's some sort
of moderation or control of those comments, I believe. I don't use
PHP, but I've heard of their documentation more than once. Looking
at it, I like it. But it's not all one big document.

The Gnome FAQ is written in DocBook using the <qandaset> tags (QandA
for question and answer) and lives in CVS. It gets built by a script
which just runs db2html on it and then puts the HTML results on the
web page. Because it's in CVS, anyone can alter it (but if they don't
update the Changelog, I'll mutilate 'em :)) Note it has to be DocBook
3.1 or later: 3.0 didn't have the <QandA*> tags. It's actually dead
easy, although DocBook involves either learning an editor with some
form of DocBook, general SGML or auto-completing-tags support or 
accepting you'll be doing a -lot- of typing. The tags are verbose :)

The docs on developer.gnome.org are also generated by scripts which
Just Run Automatically periodically and create HTML which then appears
on d.g.o. 

FAQ-O-Matic: 
	http://faqomatic.sourceforge.net/
Best starting point for Wiki I could find: 
	http://c2.com/cgi/wiki?StartingPoints
The PHP Annotated Manual:
	http://www.php.net/manual/
Stuff about the notes themselves:
	Errk, http://www.php.net/manual/about-notes.php is the best
 	I can find but it doesn't say how to set them up. Something
	tells me it will be done with PHP :)


Telsa