Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Zope: Web

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

 

 

Zope web RSS feed   Index | Next | Previous | View Threaded


simon at joyful

Nov 7, 2006, 10:20 AM

Post #1 of 1 (1226 views)
Permalink
Re: FAQ writing tips (Re: combining all zope2 FAQs into one big one at wiki.zope., org/zope2)

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
>

_______________________________________________
Zope-web maillist - Zope-web [at] zope
http://mail.zope.org/mailman/listinfo/zope-web

Zope web RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.