RTFM? IWMITWAFM! (Was: Re: [Zope] WebDAV, Zope, M$ and implications...)

Douglas Carnall dougie@carnall.org
Fri, 08 Mar 2002 14:21:34 +0000


Dieter Maurer wrote:
> Come on. Start searching. Try what you found.
> If there remains a problem, look again at the archives and when
> that does not help, come again with a precise question.

Just to test a point, I tried the search Andreas described earlier (on
"andreas jung webdav office" at http://www.zope.org/SiteIndex/searchForm
searching only on lists.zope.org). It pulled up 21 hits (3 google pages) to
posts submitted over the period Aug 2001 - Feb 2002.

It's certainly not immediately apparent where to begin on the issue. And
there's no easy way on Google that I know of to rank stuff by date. Viewing
each message one by one will certainly take more than 15 minutes: and with
no guarantee of success.

Using the archives isn't that much fun either: it's the default pipermail
situation. With heavily-trafficked lists like zope@zope.org there's a 1000+
messages so **the index** of a month's worth is a page of 150kb+ or more.
Maybe other people are luckier that me (I have a 115kbit/s connection), but
even so I'm waiting 16 seconds just to begin to find headers that **might**
be relevant, never mind the time for reading and downloading each one
individually.

Andreas Jung wrote:
> You can not expect to have a How-To for every purpose - neither for Zope
> nor for other systems. The Zope community is usally very helpful in solving
> problems. Because this particular problem has been solved and discussed
> I feel free to point you to the former discussions. All of our time is
> limited -
> and instead of repeating the same stuff over and over again it is legitimate
> from my view to answer your question in the way I have done it.

While the documentation lies locked up in obscure email threads, you are
doomed to repeat yourselves over and over because it's easier for people
with questions to post to the list than search the archives. And don't
forget you are familiar with the archives, while someone coming to solve an
issue may not be. At some point this situation fails to scale, which is why
FAQs, HOWTOs, and mini-HOWTOs and manuals were invented.

Note also that each time you fail to state the URL of the thread that first
discussed an issue you are failing to utilise Google's main advantage which
is to increase the importance score of more linked-to pages.

Relying on the archives as the definitive documentation imposes a serious
drag on anyone working on Zope. It's easy for dilettantes like me who  have
only a few hours a week to give to Zope: the approach you suggest makes
learning Zope seem insurmountable, and I can look elsewhere. But it must be
tough for anyone working on a deadline using Zope. Perhaps this what you
want? The cynical thought occurs to me that the worse the documentation, the
higher the consulting fees, the greater the book royalties.

I'm glad I don't rely on it for anything serious (and I can't say I'd
recommend it to others in its present state).

RTFM? IWMITWAFM! (I wouldn't mind if there was a fine manual!)

D.

The documentation is the software.
-- 
Douglas Carnall

tel:+44 (0)20 7241 1255
fax:08700 557879 
mob:07900 212881
http://www.carnall.org/
dougie@carnall.org