Re: constructive criticism

[Han-Wen Nienhuys]

address@hidden writes:
> I humbly find it unfair that you didn't quote the clause:
> 
> >> unless the reporter literally includes the piece of text
> >> she wants
> 
> But anyway, I'm now aiming at giving you *patches*, which
> you prefer even to bug reports, don't you?


My wish list for suggestions of the manual, ranked from most to least
desirable:


* Patches, containing well-written and well-edited updates and
  refinements of the manual.

* Bugreports, indicating specific deficiencies of manual sections 
  that are unclear

* Patches, containing updates and refinements of the manual.  I
  Usually I have to rewrite these, since they're often not
  well-written.

* Website comments/wikis, where I have to dig through a text to figure
  out what is not clear and why.

Then there is the option of setting up a FAQ/Wiki/whatever that is
separate from the manual. You have my blessing to do what you like,
and it's probably best to ignore me, because I have grown cynic over
the years. I have one advice: just do it!

> > FYI: We started and filled a wikiwiki some three odd years
> > ago, when wikiwikis were the next hot thing.  We decided
> > to take it off line last year, because the experiment
> > failed.  It is yet another potential source of information
> > to track, it grows stale and it had hardly any
> > contributors besides the developers.  Although there are
> > exceptions, lowering the threshold only yields less useful
> > information.
> 
> Ok, I really did not know about this.  My theory, which is
> exclusively mine and invented be me alone, is that linking
> it from the individual manual pages would help a lot.  Of
> course, in practice theory and practice are often different.
> I admit I have no experience besides the Haskell Wiki, which
> works pretty well serving an identical purpose.

Keep in mind that a succesful wiki needs big and active community of
people maintaining it. 

> That's fair.  Well, before posting I had a look at the
> .itelys, since I happened to have a source tree handy.  You
> don't expect users have it, do you?  Anyway, the point is
> writing/fixing/asking *while* reading, as opposed to
> updating from cvs, searching and modifying a file in an
> editor, diffing, posting and waiting for the changes to
> appear.

You know, if you type "make web", the changes appear automagically on
your own harddisk. Not much waiting needed.

-- 

 Han-Wen Nienhuys   |   address@hidden   |   http://www.xs4all.nl/~hanwen