RE: bored with *talks* about docs (was: New documentation project ?)

[H....@MI.unimaas.nl]

Guys,

I've been quiet on this one simply because I was too busy with the myriad of
crises that required my attention. The Cocoon documentation project is still
on the backburner, it's surely not cold.

With a full-time job, a husband and two small kids, and a household on my
plate, there is little time left to do major work on the Cocoon
documentation.

I'm not a great technical writer, although I've done my share of writing and
even had a "language" study before I started computer science. I also have
my specific interests in the vast amount of topics in Cocoon, so I'll
probably not be writing across the entire spectrum.

I do welcome any initiative to improve the documentation, but every thread I
read about it either went dead in a few weeks, or went down the techie trail
very quickly. Up to now in this entire thread I haven't read much more than
I've read in the previous attempts.

I just read the ExtremeDocumentationOverhaul. Great, more or less what I had
mind although not as well thought out and certainly not as well written out.
What _isn't_ there is actual content. For now, I try to hunt down
information and put links on the Cocoon215TOC wiki page. I know, it's not
the best, nicest, most coherent solution, but at least it provides a
starting point, both for users and for any documentation team.

How do you plan to get the documentation you're looking for? I don't suppose
your days contain much more spare time than mine and I also don't think you
have a vast team of skilled technical writers at hand. 

My final goal is still a documentation website that is good enough for
publication in a book and would contain all the ideas you wrote down. But my
idea is to start small, accept that the process is slow, with countless
"start" and "stop" times, when other projects need much more priority. The
idea is to to leave something useful behind every time you stop. Not only
because this might be the last time you've worked on it for a long time and
because then it is already useful to others. The process should also be easy
to take up again. You don't want to spend 80% of your time on getting the
system up and running and 20% of the time on actual documentation. If you
have only 15 minutes and it takes you 12 to write that great piece of
information you found down and 3 more to put it in the wiki, you'll do it,
but if you have to spend 10 minutes figuring out how to write that
information down according to the "rules" set out by the documentation
framework, you won't even start and the information just sits on your
harddisk or worse even, in your head.

I do hope your efforts take the documentation further than mine, and I'm
willing to contribute, but don't expect to make many miles in a short time
with just volunteers.

Bye, Helma

---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org

Re: bored with *talks* about docs (was: New documentation project ?)

[Bertrand Delacretaz <bd...@apache.org>]

Hi Helma,

Thanks very much for your realistic comments and approach, I think this 
sums it up very nicely:

> ...my
> idea is to start small, accept that the process is slow, with countless
> "start" and "stop" times, when other projects need much more 
> priority... The
> idea is to to leave something useful behind every time you stop....

I think that's the key - leaving something useful behind you every time 
one finds some time to work on this. Very well said.

-Bertrand

RE: bored with *talks* about docs (was: New documentation project?)

[David Leangen <dl...@canada.com>]

Hi, Helma,

Excellent points and great ideas!


> I just read the ExtremeDocumentationOverhaul. Great, more or
> less what I had mind although not as well thought out and
> certainly not as well written out.

Do you mean that it's not as well written out as the extent to which you've
thought it through? Or that you've already written out your own plan?

Either way, I am _very_ interested in hearing your ideas. Please feel free
to contribute to that page. :-)

Note: it's a work in progress...


> My final goal is still a documentation website that is good enough
> for publication in a book and would contain all the ideas you wrote
> down.

Oh, that's very interesting! Is there anybody else like you lurking around,
I wonder?


> [...] but if you have to spend 10 minutes figuring out how to write
> that information down according to the "rules" set out by the
> documentation framework, you won't even start and the information
> just sits on your harddisk or worse even, in your head.

That's an excellent point.

I guess that I don't mind volunteering to accept content and inserting it
myself into the "framework", if there is one.


> I do hope your efforts take the documentation further than mine, and
> I'm willing to contribute, but don't expect to make many miles in a
> short time with just volunteers.

Nah. Been there, done that. I do appreciate the friendly reminder, though.


Regards,
Dave




---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@cocoon.apache.org
For additional commands, e-mail: users-help@cocoon.apache.org