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... Matthias -----Original Message----- From: Torsten Curdt [mailto:[EMAIL PROTECTED]] Sent: Thursday, March 07, 2002 11:14 AM To: [EMAIL PROTECTED] 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 are > 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 glistening > as Cocoon, or that the docu has to be enhanced for dummies like us, be it a > 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... -- Torsten --------------------------------------------------------------------- Please check that your question has not already been answered in the FAQ before posting. <http://xml.apache.org/cocoon/faqs.html> To unsubscribe, e-mail: <[EMAIL PROTECTED]> For additional commands, e-mail: <[EMAIL PROTECTED]>
