2.2 Docs (was Re: [vote] Release Cocoon 2.2-final)

[Andrew Savory <as...@apache.org>]

Hi,

(Changing subject, starting new thread. Please, when an email says
'this thread is for votes only', try to respect that!)

On 03/04/2008, Luca Morandini <lm...@ieee.org> wrote:
> Carsten Ziegeler wrote:
>
> > We might not get some new users because of bad docs, but we might get
> people really interested in a new Cocoon.
> >
>
>  Does it mean we already gave up with attracting new users ?
>
>  What's the "mission" of 2.2 then ?

No, releasing without complete docs does not mean giving up on
attracting new users. There have been many initiatives over the years
to improve our docs but ultimately the problem remains: writing docs
is hard and boring, and people are rarely willing to do this on a
voluntary basis.

We should accept this and get 2.2 out the door (honestly, I think
delaying it further will lose more users than not having sufficient
docs) and then if we can, turn some of the energy of this debate into
writing docs. Better yet, let's be diligent in taking questions on the
mailing lists and turning them into FAQs/documentation, and improve
the docs that way.

Or if anyone knows a good technical author who might be willing to
participate in GSoC, please speak now!


Andrew.

Re: 2.2 Docs (was Re: [vote] Release Cocoon 2.2-final)

[Jeroen Reijn <j....@onehippo.com>]

Andrew Savory wrote:
> Hi,
> 
> We should accept this and get 2.2 out the door (honestly, I think
> delaying it further will lose more users than not having sufficient
> docs) and then if we can, turn some of the energy of this debate into
> writing docs. Better yet, let's be diligent in taking questions on the
> mailing lists and turning them into FAQs/documentation, and improve
> the docs that way.
> 

I agree with Andrew on this part. Delaying 2.2 even more would not be a 
good signal too our users. Maybe we can arrange some things about 
documentation at the upcoming ApacheCon?
I have not been able to find some descent time the past couple of months 
to work on Cocoon, but during the ApacheCon i might be able to find some 
time during sessions.

For those that indicate that the documentation needs to be improved 
before this release, maybe we can setup a list of missing things?



-- 
Kind regards,

Jeroen Reijn

Hippo

Amsterdam - Hippo B.V. Oosteinde 11 1017 WT Amsterdam +31(0)20-5224466
San Francisco - Hippo USA Inc. 101 H Street, suite Q Petaluma CA
94952-3329 +1 (707) 773-4646

www.onehippo.com info@onehippo.com

Re: 2.2 Docs (was Re: [vote] Release Cocoon 2.2-final)

[Grzegorz Kossakowski <gr...@tuffmail.com>]

Andrew Savory pisze:
> Hi,
> 
> (Changing subject, starting new thread. Please, when an email says
> 'this thread is for votes only', try to respect that!)
> 
> On 03/04/2008, Luca Morandini <lm...@ieee.org> wrote:
>> Carsten Ziegeler wrote:
>>
>>> We might not get some new users because of bad docs, but we might get
>> people really interested in a new Cocoon.
>>  Does it mean we already gave up with attracting new users ?
>>
>>  What's the "mission" of 2.2 then ?
> 
> No, releasing without complete docs does not mean giving up on
> attracting new users. There have been many initiatives over the years
> to improve our docs but ultimately the problem remains: writing docs
> is hard and boring, and people are rarely willing to do this on a
> voluntary basis.

Speaking about myself only but I have never found writing docs boring. Moreover, I've expierienced 
Cocoon bugs that were much more difficult to fix than any docs page to write.

Not sure why others find it boring. Don't you like to boast about your knowledge?

> We should accept this and get 2.2 out the door (honestly, I think
> delaying it further will lose more users than not having sufficient
> docs) and then if we can, turn some of the energy of this debate into
> writing docs. Better yet, let's be diligent in taking questions on the
> mailing lists and turning them into FAQs/documentation, and improve
> the docs that way.

+1

> Or if anyone knows a good technical author who might be willing to
> participate in GSoC, please speak now!

GSoC is about delivering code not documentation, see:
http://code.google.com/opensource/gsoc/2008/faqs.html#0.1_doc_proposals

-- 
Grzegorz Kossakowski