cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Matthias Fischer" <>
Subject Problems with docu
Date Tue, 12 Mar 2002 07:30:41 GMT
After a small break during which I wasn't in the office: Thorsten, I meant
item 2 of your mail - completeness and understanability for non-technicians,
especially non-Java-cracks; explaining all terminology before starting, even
if it is clear to the writer of the docu, etc. The same relates to
developers' answers in the mailing list(s): please don't forget that (a) not
everybody is a native English speaker, and not everybody is equally good at
English, (b) not everybody is a Java crack and (c) not everybody uses the
same set of terminology you are used to use (example: what the hell is a
"cvs head version"? Where is this term explained in a glossary of the Cocoon
(or the Apache XML, or the Apache home) page? Answer: nowhere...)

Item 1, up-to-dateness, is not a problem (at least to me), as it cannot be
possibly accomplished in a more satisfactory way than it already is, with
"flocks" of developers never really stopping to develop the program, but
evolving it permanently. You would have to create a locked system into which
program patches can be uploaded by developers only together with a relating
piece of docu and get the developers' consent that they would use the
system - you d'better forget about this idea...

Your remark, that everybody (i.e., including me and Adnan) could contribute
docu is appropriate. Users (i.e. non-developers who get things to work)
could be "lured" into doing so by a content management interface, something
like a three-or-four-field form, with one field for the item treated, one
for keywords to be used by a search engine, one for descriptive text and one
for pieces of code (no, better a five-field form, with an additional
compulsary field for the author's e-mail address to involve the colleague in
answering questions...) Add a button for tagging highlighted text/code for
insertion into an automatically generated index, and you can build a very
useful search engine on top of the contributed patches...


-----Original Message-----
From: Torsten Curdt []
Sent: Thursday, March 07, 2002 11:14 AM
Subject: RE: AW: Problems with font embedding

On Thu, 7 Mar 2002, Matthias Fischer wrote:

> I've got a diofferent opinion. I've done technical docu for several years:
> the criterion of measurement of a docu is its user!

For sure... but then you also should know that docu for software that is
still (fast) progressing *cannot* be up-to-date. I will not bend on this
one... ;)

> Thus, if I assure you that we read the stuff through and through, there
> only two alternative interpretations: either that we are as dumb as hell,
> and that we'd better leave our fingers off a tool as blinking and
> as Cocoon, or that the docu has to be enhanced for dummies like us, be it
> time-consuming thing or not. Nothing inbetween, as far as I know.

I guess noone wants to argue about the above... so you say the docu needs
to improved to be...

1. more up-to-date
2. more understandable for non technical users

Currently I see 1. as a problem and will only happen for each release...
Don't know about 2. though...

But as always - it's OSS. So feel free to provide a patch for the docu...
Especially if you get things working...

Please check that your question has not already been answered in the
FAQ before posting. <>

To unsubscribe, e-mail: <>
For additional commands, e-mail: <>

View raw message