Bertrand Delacretaz said the following on 18/10/06 13:56:
Thanks Arje for starting this thread.
+1
Guys,
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 cocoon.apache.org
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
whatever
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
thread.
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
