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

Simon Michael simon at joyful.com
Tue Nov 7 13:20:45 EST 2006

cc'ing from zope list:
> 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

More information about the Zope-web mailing list