cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hepabolu <>
Subject Re: [RANT] The Cocoon website: move on, nothing is happening here
Date Wed, 18 Oct 2006 15:00:10 GMT
Bertrand Delacretaz said the following on 18/10/06 13:56:
> Thanks Arje for starting this thread.



since the documentation is my main focus, I want to chime in here.

Re the redesign of the website:

I haven't discussed this much with Reinhard, but my intention was a new 
revamped website once 2.2 is released. Revamped does not only include 
new shiny looks, but IMO also a restructuring of the info and a more 
lively homepage. When Daisy was put up on the zones as our main 
documentation repository, I had already planned for a restructuring, but 
arguments that the URL space had to be preserved prevented this. So I 
decided to comply and wait for 2.2.

Re the information is all over the place:

I fully agree and since I became committer I've tried several times to 
get the role of at least the website and the wiki clear. I won't bother 
now to find all these threads. The discussions either turned into yet 
another tooling proposal or faded out when other more code-related 
topics appeared.

My own lack of time and the fact that I wasn't able to 
motivate/scare/bribe/kick the rest of the community into writing 
documentation hasn't added much to the process. I do have to say that 
this didn't boost my motivation either.

I know that open source projects thrive on voluntary work and that we 
should be grateful for all the work that's contributed, but I cannot 
dismiss the feeling that documentation is generally considered to be 
done "by someone else", while we all curse the moment when we turn to 
the documentation and find it inadequate.

I know that the current process of updating the 
website is cumbersome, but still it's a whole lot better than the 
previous process. I really don't care if it takes one step or twenty, if 
in the end all I need to do is set a timer that reminds me to provide my 
username/password to start the update process every X days, I'd be glad 
to do that.
However, that doesn't make sense when nobody bothers to write.

Moving over the legacy documentation at the time was done with reuse in 
mind. However, that means that people, knowledgable of the topic, have 
to go over it and verify it. No such actions, give or take a few, have 
been done.

Several people have written how documentation should be written and when 
I read the recent version I bitterly remembered reading almost identical 
stuff written by Dianne Shannon way back then. However, only few actual 
pages have been written.

I've spent both Hackathon days implementing the documentation 
infrastructure Reinhard has designed. Although I see some advantages in 
his setup, I didn't feel any pride over it. I merely contributed to more 
  metadata, no actual documentation.

This is where I think the main problem lies:
- discussions on documentation on the mailinglists swerve off topic and 
into tooling and code before the fifth reply is in.
- documentation is regarded as something evil/boring/without merits or 

I agree with Bertrand that we should take small steps, but let's define 
the steps first and agree on this, put them up somewhere and stick to 
them. Let's not wait for the miracle of self-describing documentation, 
or the overall genius (me ;-) ) that can write it overnight. Let's 
simply agree that it's part of the job and should be done as well.

For all the roadmaps that have been written, discussed and discarded, 
let us now finally write one for the documentation and stick to it. Use 
some of your code hacking time to write documentation. Don't wait for 
others to do, be the first to write.

If you think documentation has to be perfect in the first instance, 
you're wrong. The only thing necessary is the correctness of the 
information. If you write it down in notes, full of spelling errors and 
grammar clashes, nobody cares and I'd be glad to go over it and polish 
it up.

My proposal is: I start several new threads regarding the documentation 
on this mailinglist. Each thread contains a single topic, e.g. "position 
of wiki vs Daisy", "documentation structure", "documentation roadmap".

We can discuss the various ideas but WE REMAIN ON TOPIC or start a new 

The end result should be one or more documents in Daisy that express our 
consensus on what the documentation should look like and how each 
community member can contribute and which rules we have to live by (e.g. 
no code release unless there is sufficient documentation).

And once we agree (whether through voting or through general consensus I 
don't care), we stick to it and follow it through.

Sorry if this sounds a bit emotional, but that's how I feel.

Bye, Helma

View raw message