cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From beyaNet <and...@jibeya.com>
Subject Re: bored with *talks* about docs (was: New documentation project?)
Date Sat, 13 Nov 2004 11:39:15 GMT
Bertrand,
I'm inclined to agree with your point of view. The community knows that 
things can be improved in terms of documenting cocoon so let's, instead 
of having the mother of all discussions about the blatantly 
self-evident, now concentrate on putting some flesh on this discussion.

regards

Andrew

p.s. just had 2 hours sleep!!
On 13 Nov 2004, at 11:31, Bertrand Delacretaz wrote:

> Le 13 nov. 04, à 05:36, David Leangen a écrit :
>
>> ...Not sure if I'm making myself clear, but I'm interested in hearing 
>> others'
>> thoughts on this approach...
>
> You might want to take what follows with a grain of salt, please don't 
> be offended.
>
> (First a bit of context to help you understand: it's a grey saturday 
> morning here, I went to bed too late, I have a bit of flu and I've 
> been feeling bad about Cocoon docs for at least two years without 
> really being able to do much to improve it. Now the stage is set: old 
> grumpy man here ;-)
>
> So here we go: I'm a bit bored about all these discussions about our 
> docs. Yes, we know our docs are suboptimal.
>
> Problem is, every now and then, people (myself included, I've been 
> guitly of this *several times* actually ;-) come up with bright new 
> ideas about improving our docs, lots of really interesting talks, 
> but...nothing really happens.
>
> I think it's the same with code or docs or everything: we could talk 
> for ages about the best way of doing things, but unless actual, 
> concrete, real, tangible stuff happens, it's just talk.
>
> Do you want better docs? Fine, so do I, so do most people here.
> I'd love to have more time to work on them - I don't, so is life for 
> me at this point unfortunately.
>
> Do you have resources to make it happen, or at least create a 
> reasonably-sized "seed" of what the new docs could be? Then go for it! 
> This will make all the difference.
>
> Don't ask around too much, you know the need and will is here - just 
> do it, import the good parts of the existing docs (there *are* quite a 
> lot of good parts actualy hidden in there) into whatever system you 
> feel is good to use, create a live, tangible, concrete example of what 
> the new docs will be and *convince people* that it's the way to go - 
> by *showing them* the actual thing, flesh and bones.
>
> Our wiki, even with all its flaws, has shown that this can work and be 
> an improvement: things were much worse before we had the wiki. Some 
> people created it (a long time ago ;-), put initial content in it, 
> this convinced others that it was a Good Thing and people started 
> added content to it. It worked. To a point, but it's been a big 
> improvement already.
>
> I'm not saying that our wiki is fantastic, but the *process* of 
> planting an initial seed has worked once - let's make it work once 
> again.
>
> Once again, don't get me wrong: I'm talking to myself here as much as 
> to everybody else, but I hope you get the point: you have good ideas 
> for our docs: then just go for it!
>
> Hope this helps..
>
> -Bertrand
>

Mime
View raw message