Documentation and repeats, was Re: Having problems with finding screens

[Scott Anderson <sa...@ttm.com>]

Jon Stevens wrote:
> 
> I get tired (and seeing others do it) of repeating the same thing over and
> over and over again and given that you are reading the archives...

Which is a valid complaint.

However, please understand that I *do* read the archives (all 1.6M of
them), and the website, and the included documentation. I do not ask
questions *until* I have a problem that I can't solve on my own, or if I
can't find something. 

Again, if the documentation were organized in a better fashion, you
would not be getting repeat questions. New people in open source
projects are quite content to ask questions of the old-timers if they
can't find the answer easily in the docs; hence you would probably be
well served to add the things you have repeated more than once to the
documentation or FAQ. Expecting every new user to just jump right in and
submit changes is a bit unrealistic as the typical new user is having
enough problems coming up to speed on a new system. Additionally, YOU
are in the best position to know where, how, and what to add to the
documentation in order to bring it up to speed, not someone who has been
using the TDK for all of a day and a half.

In other words, users in open source projects are there to beta test
both the code AND the documentation. While your code may work fine, it
is obvious that there are other areas that need more attention.

I've seen more than one project like this falter because the
documentation was out-of-date, apocryphal, or just plain non-existent.
With respect to Turbine in particular, I've read things several times
and then had a hell of a time finding where I read it later. Most of the
time I have to resort to find . | xargs grep, and that is hit or miss if
I can't remember the keywords.

Turbine is a very fine piece of work, but you don't encourage people to
contribute by berating them on public mailing lists. :-)

Regards,
-scott

---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-user-help@jakarta.apache.org

Re: Documentation and repeats, was Re: Having problems with finding screens

[Jon Stevens <jo...@latchkey.com>]

on 3/27/01 12:18 PM, "Scott Anderson" <sa...@ttm.com> wrote:

> I've seen more than one project like this falter because the
> documentation was out-of-date, apocryphal, or just plain non-existent.

This project has been going strong for about 4 years now. I don't think it
is faltering at all. We have an excellent codebase and a diverse, strong and
*very smart* community.

> Turbine is a very fine piece of work, but you don't encourage people to
> contribute by berating them on public mailing lists. :-)

And my point being that if I spend time telling you something, I expect you
to listen to it. :-) There have now been a couple cases now where I have had
to repeat the same thing because you didn't see it the first time.

    #1. The correct URL to use. Not only is that in the documentation for
        the TDK, but I also stated it on the list.

    #2. The methodology for editing the documentation is on the website and
        in the archives of the list.

    #3. I pointed at the Pull Model.

Yes, I agree, documentation is Turbine's weakest point and always will be
(you can never have enough examples that tell people how to write their
code), but, if I write documentation all day long and you don't read it,
what is the point?

-jon


---------------------------------------------------------------------
To unsubscribe, e-mail: turbine-user-unsubscribe@jakarta.apache.org
For additional commands, e-mail: turbine-user-help@jakarta.apache.org