Personality in docs (Was: Re: 'Production' build for Cocoon?)
Roger I Martin PhD wrote: Right now INSTALL.txt needs some things cut out of it: [stuff-snipped] I'd like to point out a few Theses of the Cluetrain which apply here: 14. Corporations do not speak in the same voice as these new networked conversations. To their intended online audiences, companies sound hollow, flat, literally inhuman. 15. In just a few more years, the current homogenized voice of businessthe sound of mission statements and brochureswill seem as contrived and artificial as the language of the 18th century French court. 16. Already, companies that speak in the language of the pitch, the dog-and-pony show, are no longer speaking to anyone. 17. Companies that assume online markets are the same markets that used to watch their ads on television are kidding themselves. 18. Companies that don't realize their markets are now networked person-to-person, getting smarter as a result and deeply joined in conversation are missing their best opportunity. 19. Companies can now communicate with their markets directly. If they blow it, it could be their last chance. 20. Companies need to realize their markets are often laughing. At them. 21. Companies need to lighten up and take themselves less seriously. They need to get a sense of humor. 22. Getting a sense of humor does not mean putting some jokes on the corporate web site. Rather, it requires big values, a little humility, straight talk, and a genuine point of view. I don't mind making the docs a little more pofessional sounding but I'd really, really hate to see the personality stripped from them as well. We're all people here, not robots. I'd rather read someone's genuine opinion about why Cocoon kicks so much ass instead of reading about the latest buzzword of the day. Tony
Re: Personality in docs (Was: Re: 'Production' build for Cocoon?)
Tony Collen wrote: I don't mind making the docs a little more pofessional sounding but I'd really, really hate to see the personality stripped from them as well. We're all people here, not robots. I'd rather read someone's genuine opinion about why Cocoon kicks so much ass instead of reading about the latest buzzword of the day. +1
RE: Personality in docs (Was: Re: 'Production' build for Cocoon?)
Being the guy that started this little storm I thought I'd wade in with my 2 cents worth... I don't mind the humour in the install.txt. I thought it was refreshing to see somebody who admits that by-and-large, developers hate reading docs and would rather just dive in and figure it for themselves. Granted, if the reader is not a developer, but somebody less tech-savvy (say, a Project Manager) then I could certainly see where the humour could be lost on them and make a bad first impression. I think everything could be improved with slightly better organization. I was looking for information on building a Production build. So I looked for build or deploy documents. I didn't think of going back to the install.txt (after all, I had already installed it, right?), although I had read the entire file when I downloaded and installed it the first time. If it were up to me (and yes, I know it could very well be if I had the time!), I would create a readme.txt that would point the user to one of install.txt, build.txt, deploy.txt and maybe an overview.txt or welcome.txt. The install could be left pretty much the same (just make sure there's a link to the website with all the version-specific helps). The build.txt could cover the modifications to the local.build.properties and maybe go into a bit more detail (sentence each) on what the various things control. The welcome/overview could be targeted at the less tech-savvy crew (with appropriate language/tone). So, my vote would be to keep the personality, just flesh out what's there a little more and maybe make a concessionary personality-free doc for the non-developer audience that expects sterile business language. Cheers, Chris -Original Message- From: Tony Collen [SMTP:[EMAIL PROTECTED] Sent: Tuesday, August 26, 2003 12:54 PM To: [EMAIL PROTECTED] Subject: Personality in docs (Was: Re: 'Production' build for Cocoon?) Roger I Martin PhD wrote: Right now INSTALL.txt needs some things cut out of it: [stuff-snipped] I'd like to point out a few Theses of the Cluetrain which apply here: 14. Corporations do not speak in the same voice as these new networked conversations. To their intended online audiences, companies sound hollow, flat, literally inhuman. 15. In just a few more years, the current homogenized voice of business - the sound of mission statements and brochures - will seem as contrived and artificial as the language of the 18th century French court. 16. Already, companies that speak in the language of the pitch, the dog-and-pony show, are no longer speaking to anyone. 17. Companies that assume online markets are the same markets that used to watch their ads on television are kidding themselves. 18. Companies that don't realize their markets are now networked person-to-person, getting smarter as a result and deeply joined in conversation are missing their best opportunity. 19. Companies can now communicate with their markets directly. If they blow it, it could be their last chance. 20. Companies need to realize their markets are often laughing. At them. 21. Companies need to lighten up and take themselves less seriously. They need to get a sense of humor. 22. Getting a sense of humor does not mean putting some jokes on the corporate web site. Rather, it requires big values, a little humility, straight talk, and a genuine point of view. I don't mind making the docs a little more pofessional sounding but I'd really, really hate to see the personality stripped from them as well. We're all people here, not robots. I'd rather read someone's genuine opinion about why Cocoon kicks so much ass instead of reading about the latest buzzword of the day. Tony
Re: 'Production' build for Cocoon?
Hi Antonio, At the moment I'm checking out Lenya by CVS so I can understand it's impact on the use of Cocoon and webapp design. Then I'll get back to you on what Cocoon's INSTALL.txt needs added. Right now INSTALL.txt needs some things cut out of it: snip Let me guess: you don't like to read verbose docs, right? Great, this file is for you. /snip snip your mileage may vary depending on your shell, but you know how to setup environments, right? /snip snip That's it! Now, you have two choices: a) close this file and try to hack something out by yourself b) keep reading Go ahead and choose option a), but don't complain if you can't figure out how to use the cocoon build system for your needs. Still here? good. You won't regret it. /snip snip All right, that's it for now. Happy hacking with Cocoon. /snip Would you rather a CVS patch that removes these? Typos and English troubles are not a problem. A good editor can solve those quickly. It's coyness, obnoxious playing with people new to Cocoon in the first documents they read that lowers first impressions. The overview on http://cocoon.apache.org/ gives a good first impression. Where is the person who wrote it? br, Roger BTW, it is fine for email between developers to have typos, English problems and self expression :-) One thing I do note is many take snips out of other people's email to express themselves about said snippet and lose the context like a bunch of quibbling Biblical scholars:-) Perhaps someday instead of using email lists we can use a Content Management System where we can link to reference a particular piece of writing we're wanting to discuss. - Original Message - From: Antonio Gallardo [EMAIL PROTECTED] To: [EMAIL PROTECTED] Sent: Saturday, August 23, 2003 12:32 PM Subject: Re: 'Production' build for Cocoon? Hi Roger: Can you write the intro as you suggested? Please don't take this question in the bad sense. I think all of us can help to make a better Cocoon. We are a community with a common interest called Cocoon framework. I meet Cocoon a year ago (I still consider my self a newbie in Cocoon). From my point of view, there has been an amazing improvement in the Cocoon documentation: Currently, we have 3 printed books released in less than a year, a nice (still growing) wiki site with many info and helps docs to read and at the end but not the last important a better official cocoon documentation. A year ago there was nothing like that, just some docs in the official cocoon site and a handfull articles somewhere in the vast Internet. It is really amazing how long the project growed in the last year. I saw that. Well, as usual, nothing is perfect and because of that we are still working to improve Cocoon framework every day. I encourage you to join us an helps in this wonderful project. From my own experience in the project I learned that: Critics are always welcomed, because helps to improve the framework. But solutions are better welcomed. By solutions I mean a patch that address a particular problem someone see. Remember that this is a multi cultural community that try to use a unique language (english). The skill of written english that members use is very diferent. From totally beginners to people with great skill to write english. This is a fact. Take my own example: To write this mail I need more than 30 mins. I need to review what I wrote to make sure if my message carries what I mean and I know still there are many errors and sometimes after my own review my message is not carried in the lines. But is is not because I am a stupid, this is because simply my mother language is not english. For there reasons, I think we need people with better skill of written english to help us to write and improve the docs. And if this is your case I encourage you to helps us to write your requested INSTALL.txt :) As usual, when there is nothing, the first draft or the first block of the construction is hard to put, after that when we have something then improve it is easier! Please try to write the first draft. :) At the end I want to write a phrase from a song from Pink Floyd: Together we stand, divided we fall :) Best Regards, Antonio Gallardo P.S: I dont want to fight with nobody here and I am not trying to attack nobody. Please take my message in the most good sense. Really we need to work together :)
Re: 'Production' build for Cocoon?
Roger I Martin PhD wrote: Hi Antonio, At the moment I'm checking out Lenya by CVS so I can understand it's impact on the use of Cocoon and webapp design. Then I'll get back to you on what Cocoon's INSTALL.txt needs added. with regard to your recent emails better don't look at the Lenya INSTALL.txt ;-) it's basically a white sheet ... ... but any help on improving them is very welcome (especially generating them out of some XML) Michael Right now INSTALL.txt needs some things cut out of it: snip Let me guess: you don't like to read verbose docs, right? Great, this file is for you. /snip snip your mileage may vary depending on your shell, but you know how to setup environments, right? /snip snip That's it! Now, you have two choices: a) close this file and try to hack something out by yourself b) keep reading Go ahead and choose option a), but don't complain if you can't figure out how to use the cocoon build system for your needs. Still here? good. You won't regret it. /snip snip All right, that's it for now. Happy hacking with Cocoon. /snip Would you rather a CVS patch that removes these? Typos and English troubles are not a problem. A good editor can solve those quickly. It's coyness, obnoxious playing with people new to Cocoon in the first documents they read that lowers first impressions. The overview on http://cocoon.apache.org/ gives a good first impression. Where is the person who wrote it? br, Roger BTW, it is fine for email between developers to have typos, English problems and self expression :-) One thing I do note is many take snips out of other people's email to express themselves about said snippet and lose the context like a bunch of quibbling Biblical scholars:-) Perhaps someday instead of using email lists we can use a Content Management System where we can link to reference a particular piece of writing we're wanting to discuss. - Original Message - From: Antonio Gallardo [EMAIL PROTECTED] To: [EMAIL PROTECTED] Sent: Saturday, August 23, 2003 12:32 PM Subject: Re: 'Production' build for Cocoon? Hi Roger: Can you write the intro as you suggested? Please don't take this question in the bad sense. I think all of us can help to make a better Cocoon. We are a community with a common interest called Cocoon framework. I meet Cocoon a year ago (I still consider my self a newbie in Cocoon). From my point of view, there has been an amazing improvement in the Cocoon documentation: Currently, we have 3 printed books released in less than a year, a nice (still growing) wiki site with many info and helps docs to read and at the end but not the last important a better official cocoon documentation. A year ago there was nothing like that, just some docs in the official cocoon site and a handfull articles somewhere in the vast Internet. It is really amazing how long the project growed in the last year. I saw that. Well, as usual, nothing is perfect and because of that we are still working to improve Cocoon framework every day. I encourage you to join us an helps in this wonderful project. From my own experience in the project I learned that: Critics are always welcomed, because helps to improve the framework. But solutions are better welcomed. By solutions I mean a patch that address a particular problem someone see. Remember that this is a multi cultural community that try to use a unique language (english). The skill of written english that members use is very diferent. From totally beginners to people with great skill to write english. This is a fact. Take my own example: To write this mail I need more than 30 mins. I need to review what I wrote to make sure if my message carries what I mean and I know still there are many errors and sometimes after my own review my message is not carried in the lines. But is is not because I am a stupid, this is because simply my mother language is not english. For there reasons, I think we need people with better skill of written english to help us to write and improve the docs. And if this is your case I encourage you to helps us to write your requested INSTALL.txt :) As usual, when there is nothing, the first draft or the first block of the construction is hard to put, after that when we have something then improve it is easier! Please try to write the first draft. :) At the end I want to write a phrase from a song from Pink Floyd: Together we stand, divided we fall :) Best Regards, Antonio Gallardo P.S: I dont want to fight with nobody here and I am not trying to attack nobody. Please take my message in the most good sense. Really we need to work together :) -- Michael Wechner Wyona Ltd. - Open Source Content Management - Apache Lenya http://www.wyona.com http://cocoon.apache.org/lenya/ [EMAIL PROTECTED][EMAIL PROTECTED]
Re: 'Production' build for Cocoon?
Antonio Gallardo wrote: P.S: I dont want to fight with nobody here and I am not trying to attack nobody. Please take my message in the most good sense. Really we need to work together :) ... and your relentless efforts at such are very much appreciated, Antonio! /Steven -- Steven Noelshttp://outerthought.org/ Outerthought - Open Source, Java XML Competence Support Center Read my weblog athttp://blogs.cocoondev.org/stevenn/ stevenn at outerthought.orgstevenn at apache.org
Re: Production build for Cocoon?
On Friday, Aug 22, 2003, at 18:05 Europe/Rome, Roger I Martin PhD wrote: For Cocoon developers: you need to start thinking of Cocoon as a servlet intended to be used inside of your customer's webapp. For Roger I Martin PhD: you need to start reading the mail list archives (or ask) before attempting to read our minds using the released software as a starting point. It helps a lot to reduce the chance of look like a pretencious ignorant. If I opened an M$ product out of the box and the way to INSTALL it was described as in INSTALL.txt with the results far from That's it! I would not hesitate to return it. In case, we'd immediately refund you and give your money back. Oh, no, wait, we are so efficient that you can find your money attached below. -- Stefano.
Re: 'Production' build for Cocoon?
Hi Roger: Can you write the intro as you suggested? Please don't take this question in the bad sense. I think all of us can help to make a better Cocoon. We are a community with a common interest called Cocoon framework. I meet Cocoon a year ago (I still consider my self a newbie in Cocoon). From my point of view, there has been an amazing improvement in the Cocoon documentation: Currently, we have 3 printed books released in less than a year, a nice (still growing) wiki site with many info and helps docs to read and at the end but not the last important a better official cocoon documentation. A year ago there was nothing like that, just some docs in the official cocoon site and a handfull articles somewhere in the vast Internet. It is really amazing how long the project growed in the last year. I saw that. Well, as usual, nothing is perfect and because of that we are still working to improve Cocoon framework every day. I encourage you to join us an helps in this wonderful project. From my own experience in the project I learned that: Critics are always welcomed, because helps to improve the framework. But solutions are better welcomed. By solutions I mean a patch that address a particular problem someone see. Remember that this is a multi cultural community that try to use a unique language (english). The skill of written english that members use is very diferent. From totally beginners to people with great skill to write english. This is a fact. Take my own example: To write this mail I need more than 30 mins. I need to review what I wrote to make sure if my message carries what I mean and I know still there are many errors and sometimes after my own review my message is not carried in the lines. But is is not because I am a stupid, this is because simply my mother language is not english. For there reasons, I think we need people with better skill of written english to help us to write and improve the docs. And if this is your case I encourage you to helps us to write your requested INSTALL.txt :) As usual, when there is nothing, the first draft or the first block of the construction is hard to put, after that when we have something then improve it is easier! Please try to write the first draft. :) At the end I want to write a phrase from a song from Pink Floyd: Together we stand, divided we fall :) Best Regards, Antonio Gallardo P.S: I dont want to fight with nobody here and I am not trying to attack nobody. Please take my message in the most good sense. Really we need to work together :)
Production build for Cocoon?
Just wondering if there's any easy way of making a Production build of Cocoon. The default build compiles all of the samples and makes them available which is fine for development. However, when we eventually go live, we'd like to be able to deploy a minimal build that doesn't have the samples or javadoc, etc. We took a quick stab once at trying to remove the samples after doing the full, default build but started running into various file-not-found problems as the master sitemap tried to load various sample-related items. We're okay with using the master Cocoon sitemap (saves us a lot of declaring and configuring) and letting it mount our stuff, but we'd like to be able to do a build that leaves out all of the samples, etc. Is this possible? Is it already there or are there some straightforward instructions on what to delete from the full build and still have things work? Thanks, Chris
RE: Production build for Cocoon?
Thanks. I had read it, but I'd forgotten about the properties files as it was some time ago and the install.txt isn't something I generally go back and read after I've finishing installing something and it's working. -Original Message- From: Giacomo Pati [SMTP:[EMAIL PROTECTED] Sent: Friday, August 22, 2003 9:25 AM To: [EMAIL PROTECTED] Subject: Re: Production build for Cocoon? Ever read the INSTALL.txt? On Fri, 22 Aug 2003, Chris Clark wrote: Just wondering if there's any easy way of making a Production build of Cocoon. The default build compiles all of the samples and makes them available which is fine for development. However, when we eventually go live, we'd like to be able to deploy a minimal build that doesn't have the samples or javadoc, etc. We took a quick stab once at trying to remove the samples after doing the full, default build but started running into various file-not-found problems as the master sitemap tried to load various sample-related items. We're okay with using the master Cocoon sitemap (saves us a lot of declaring and configuring) and letting it mount our stuff, but we'd like to be able to do a build that leaves out all of the samples, etc. Is this possible? Is it already there or are there some straightforward instructions on what to delete from the full build and still have things work? Thanks, Chris -- Giacomo Pati Otego AG, Switzerland - http://www.otego.com Orixo, the XML business alliance - http://www.orixo.com
Re: Production build for Cocoon?
Roger I Martin PhD wrote: standalone-demo build target is one of the worst ways to work with Cocoon; yet alone achieve what Chris is asking. Cocoon is a super charged super powerful servlet that can be used to achieve some pretty amazing results. I've read the INSTALL.txt and it is a excellent example of unprofessional writing. In fact it is simply obnoxious. Roger, You sound bitter, perhaps you would be willing to share some of your Ph.D. level of education and donate some better writing? Seriously, though, bitching about something without helping is pretty worthless. At least offer some suggestions rather than flamebait. Anybody can contribute, and I'm sure the developers would be more than willing to apply a patch to documentation. I consider myself a Cocoon developer even though I'm not a committer. Everybody in this community is a developer, including you. Don't forget this. Tony
Re: Production build for Cocoon?
Roger I Martin PhD wrote:
standalone-demo build target is one of the worst ways to work with Cocoon; yet alone achieve what Chris is asking. Cocoon is a super charged super powerful servlet that can be used to achieve some pretty amazing results.
I've read the INSTALL.txt and it is a excellent example of unprofessional writing. In fact it is simply obnoxious.
Please don't forget that all Cocoon developers started as Cocoon users.
So why don't you jump in and write some better install docs ? The
community would be very thankful for this.
If sending patches is too complex, you can contribute to the Cocoon
wiki, as many users do.
snip/
For Cocoon developers: you need to start thinking of Cocoon as a servlet intended to be used inside of your customer's webapp. If I opened an M$ product out of the box and the way to INSTALL it was described as in INSTALL.txt with the results far from That's it! I would not hesitate to return it.
Yeah, but with M$ you pay for that shiny box, have no way to make your
feedback heard nor to contribute back.
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Orixo, the opensource XML business alliance - http://www.orixo.com
