On 9/20/06, Christopher Browne <cbbrowne at ca.afilias.info> wrote:
> Andrew Hammond wrote:
> > D. Aggressively encourage and support feedback, especially by new
> > users so that the quality of the documentation can constantly be
> > improved.
>
> I don't know how to do this in a useful fashion.  Not to pick at people,
> but it's disappointing to see what amount to "slams" like the following:

Please don't interpret this as a slam, it's certainly not intended as
one. I just think we need to recognize the challenge of addressing
newbies. I think in order to do this, we need to find ways to make it
_very_ easy for newbies to tell us specifically where they get lost or
stuck with the current documentation.

> I'd be more than happy to respond with improvements, if something more
> specific was said than "needs *much* better docs."  I honestly don't
> know what this "Yet Another Andrew" :-) has in mind when he says
> "better."  If I did, I'd be entirely happy to try to address his issues.
>
> Unfortunately, it seems to be like pulling teeth to get responses more
> specific than "better."  This is NOT a criticism of Andrew Dunstan; his
> is an entirely typical sort of comment that I see across all kinds of
> projects (not just Slony-I).  (I suppose I'm grousing a bit; it's
> certainly not personal.  I also think BuildFarm docs could be better ;-).)

I was thinking that documentation might be served up the same way the
postgres docs are with a comment section at the bottom. Either that or
maybe a wiki. But before we talk about implementation, I think we need
to clearly identify the problem we're trying to solve. What I see from
what you're saying above is that you're not getting useful feedback
about the documentation. Perhaps that's the best way to express the
requirement is something like this.

D. Find better ways to get useful, explicit feedback about our
documentation. This especially includes lowering the barrier for new
users.

Drew