[Zope] FAQ writing tips (Re: combining all zope2 FAQs into one big one at wiki.zope., org/zope2)

[Simon Michael]

PS, here's a word of warning to FAQ writers from my own experience, a trap 
to avoid:

You start writing answers for questions - it's so easy and tempting - 
later you find better answers out on the web, even elsewhere in the same 
wiki, but now you have a big, verbose body of duplicated docs that's too 
good to throw away but not quite valuable enough to attract a lot of 
maintenance. Result: stagnation.

How to avoid this ? Maybe keeping these goals in mind will help:

- research, link, gather, consolidate docs first; write new ones as last resort

- keep answers in the faq short and to the point, link to best detailed 
docs elsewhere

- avoid unnecessary duplication. Use the contents link to see what's in the 
zope2 and other zope wikis. Refactor the wiki content aggressively when 
appropriate.

Also, long wiki pages are less fun to edit than short ones, use an external 
editor for FAQ work to avoid this pain. Emacs users, try rst-mode.el.

-Simon