newbies documentation (was: Cocoon is too complex for consumption?)
Hy; as a newbie (of three months age ;) ) i'd like to contribute my thoughts to the documentation area: 1.) From my now 20 years experience in computer art i learned that the newbies can tell much more about the features of a program, than the developers can. Why? because the newbie always tries the wrong pathes through the software therefore detect the weaknesses and strenghts of the app and often walk through pathes the developers never thought of inventing new use cases , etc. In turn the developers always are biased from their architectural insights... 2.) In several projects i was faced with the situation of lacking or inappropriate user documentation. One strategy for improvement was always to let the users start writing down what they think the app does and how they would use it. Then the developers had the time to start thinking over what they implemented. This is an iterative approach that fits better to the real world, than smacking at the developers and force them to start documenting ... My *personal* conclusions on this: 1.) Instead of shouting against the developers i started writing down my experiences within my company wiki. I did this because i wanted a clear separation from all the masters of the art articles turning up in the cocoon wiki. Besides this some of the points i tackled have to give at least little insight into tomcat and other loosely coupled themes which i didn't want to add to the ever growing cocoon wiki. 2.) Whoever writes docs for the newbies MUST get help from an experienced user or a developer at least for review. This could be the start of a productive user centric quality assurance. This may eventually get all these very interesting but (sorry) unneaded explanations of avalon and other base technologies out of the docs or at least into separated docs. 3.) Writing docs MUST be made as simple as possible. But it should be surveyed from one or a few editors who keep the docs in right shape, and right organisation. so i would propose (as Derek does): 1.) Provide a platform separate from the already existing documentation areas, which is clearly labeled as the newbies competence center, accessible to everyone with most ease (start getting productive in a minute) 2.) I would recommend to use a separate Wiki for this purpose. 3.) Instead of letting such a wiki free floating, get at least one person into the role of the responsible editor And despite any possibly upcoming thoughts like this is open source, everyone (thus noone?) is responsible i would gladly get into the role of the responsible editor for some time at least. And if it makes sense, i also would start hosting such a cocoon CC Wiki. Meanwhile i will continue writing down my personal insights and eventually donate all this stuff to whatever will come up as a newbies documentation infrastructure ... regards, hussayn Derek Hohls wrote: Tony In case you missed my other wandering thought pattern; its my strong feeling we need a SINGLE section of the website - preferably one well-insulated from the ramblings on the other site which is always under construction that (including any formal guides) solely addresses ONLY the needs of newbies and has ALL the documents AND faqs AND minimal downloads AND simple sitemaps etc in ONE place - no obscure wikis/mailing list links. (Gee, we are working with a web publishing platform here - how hard can this be to put together *technically*?? ) The trick is writing good, clear, simple pages - and that's a matter of write - read - edit recycle until your target newbie - not your average developer/contributor - can make sense of it... Derek [EMAIL PROTECTED] 27/01/2003 06:29:12 In light of this ginormous thread, do we need more newbie guides to getting started with Cocoon? Obviously the CTWIG or whatever is out of date, so perhaps there's a demand for something like a Busy Developer's Guide to getting started with Cocoon? I'd be more that willing to write stuff up that for direct inclusion with the Cocoon documentation that is distributed with the releases. If so, I'll start writing up a Cocoon BDG (or even a series) in Document 1.1 format. P.S. Docs team: Perhaps it's time to start assimilating Wiki content into the distribution docs? Tony -- Cocoon: Internet Glue (A Cocoon Weblog) http://manero.org/weblog/ - Please check that your question has not already been answered in the FAQ before posting. http://xml.apache.org/cocoon/faq/index.html To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] -- This message has been scanned for viruses and dangerous content by *MailScanner* http://www.mailscanner.info/, and is believed to be clean. The CSIR exercises no editorial control over
Re: newbies documentation (was: Cocoon is too complex for consumption?)
SAXESS - Hussayn Dabbous wrote: My *personal* conclusions on this: 1.) Instead of shouting against the developers i started writing down my experiences within my company wiki. I did this because i wanted a clear separation from all the masters of the art articles turning up in the cocoon wiki. Besides this some of the points i tackled have to give at least little insight into tomcat and other loosely coupled themes which i didn't want to add to the ever growing cocoon wiki. Hussayn, pardon my insistence, but the idea of starting yet another Cocoon documentation resource is troubling me a bit, especially if that means setting up another Wiki. Given the easy proliferation of Wiki content, people will not know anymore where to submit and retrieve information. Why not start a section within the existing Wiki? I'd be _very_ willing to provide you guys _any_ assistance you might need. And even if the users would insist in having 'their own Wiki' (although I think the existing wiki.cocoondev.org is there for _anybody_), I'd be happy in providing hosting for that under the neutral cocoondev.org domain. /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 - Please check that your question has not already been answered in the FAQ before posting. http://xml.apache.org/cocoon/faq/index.html To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: newbies documentation (was: Cocoon is too complex for consumption?)
hy, Derek; what you say makes perfect sense ;-) only one suggestion for the first two pages: 1.) HOWTO setup cocoon in 15 minutes ;-) should be easy by condensing the other thread 2.) HOWTO setup your intranet with XML in 1 day it took me two weeks to figure it out, but i could give away 2 style sheets 1 document xschema 1 sitemap that would be sufficient to drive a very basic intranet site like mine at http://www.saxess.de simply by taking the files, putting them into cocoon and then generating your content... regards, hussayn Derek Hohls wrote: A quick addition to what Hussayn suggests - which is well explained and makes perfect sense - is to take this one step further - lets have a wiki for people to add/suggest etc BUT we need to take from it the most polished and relevant material and make it into a formal and well laid-out website (yes, I do use wikis and I do host one inside my company - but they are not always very accessible or well-structured from a newbie point-of-view) - if we do our design correctly ;-) this should not require much more than a stylesheet or two for the conversion. Maybe the first topic on the Cocoon Newbie Wiki could be : Framework for a Cocoon Newbie Web (non-wiki) Site?? I second Hussayn as editor for the new site (wow, a *real* volunteer) Derek [EMAIL PROTECTED] 27/01/2003 10:52:47 Hy; as a newbie (of three months age ;) ) i'd like to contribute my thoughts to the documentation area: 1.) From my now 20 years experience in computer art i learned that the newbies can tell much more about the features of a program, than the developers can. Why? because the newbie always tries the wrong pathes through the software therefore detect the weaknesses and strenghts of the app and often walk through pathes the developers never thought of inventing new use cases , etc. In turn the developers always are biased from their architectural insights... 2.) In several projects i was faced with the situation of lacking or inappropriate user documentation. One strategy for improvement was always to let the users start writing down what they think the app does and how they would use it. Then the developers had the time to start thinking over what they implemented. This is an iterative approach that fits better to the real world, than smacking at the developers and force them to start documenting ... My *personal* conclusions on this: 1.) Instead of shouting against the developers i started writing down my experiences within my company wiki. I did this because i wanted a clear separation from all the masters of the art articles turning up in the cocoon wiki. Besides this some of the points i tackled have to give at least little insight into tomcat and other loosely coupled themes which i didn't want to add to the ever growing cocoon wiki. 2.) Whoever writes docs for the newbies MUST get help from an experienced user or a developer at least for review. This could be the start of a productive user centric quality assurance. This may eventually get all these very interesting but (sorry) unneaded explanations of avalon and other base technologies out of the docs or at least into separated docs. 3.) Writing docs MUST be made as simple as possible. But it should be surveyed from one or a few editors who keep the docs in right shape, and right organisation. so i would propose (as Derek does): 1.) Provide a platform separate from the already existing documentation areas, which is clearly labeled as the newbies competence center, accessible to everyone with most ease (start getting productive in a minute) 2.) I would recommend to use a separate Wiki for this purpose. 3.) Instead of letting such a wiki free floating, get at least one person into the role of the responsible editor And despite any possibly upcoming thoughts like this is open source, everyone (thus noone?) is responsible i would gladly get into the role of the responsible editor for some time at least. And if it makes sense, i also would start hosting such a cocoon CC Wiki. Meanwhile i will continue writing down my personal insights and eventually donate all this stuff to whatever will come up as a newbies documentation infrastructure ... regards, hussayn Derek Hohls wrote: Tony In case you missed my other wandering thought pattern; its my strong feeling we need a SINGLE section of the website - preferably one well-insulated from the ramblings on the other site which is always under construction that (including any formal guides) solely addresses ONLY the needs of newbies and has ALL the documents AND faqs AND minimal downloads AND simple sitemaps etc in ONE place - no obscure wikis/mailing list links. (Gee, we are working with a web publishing platform here - how hard can this be to put together
Re: newbies documentation (was: Cocoon is too complex for consumption?)
hy, steven; you are right: no good idea to create another documentation source. i remember, i also complained about that when i started with cocoon: documentation sites all around and uncoordinated. The point is uncoordinated here: I propose to coordinate the newbies site with the existing cocoon wiki. If this can be done technically within the same wiki, different layout, different startpage and so on, its ok for me. if it can be set up as parallel deployed JSPWiki, what the hell, a link is a link and you can interlink two wikis with ease... The major point is to remember, that the newbies wiki is a part of the cocoon wiki, independent of the underlaying technology, thus coordinating the content, not the technology. regards, hussayn Steven Noels wrote: SAXESS - Hussayn Dabbous wrote: My *personal* conclusions on this: 1.) Instead of shouting against the developers i started writing down my experiences within my company wiki. I did this because i wanted a clear separation from all the masters of the art articles turning up in the cocoon wiki. Besides this some of the points i tackled have to give at least little insight into tomcat and other loosely coupled themes which i didn't want to add to the ever growing cocoon wiki. Hussayn, pardon my insistence, but the idea of starting yet another Cocoon documentation resource is troubling me a bit, especially if that means setting up another Wiki. Given the easy proliferation of Wiki content, people will not know anymore where to submit and retrieve information. Why not start a section within the existing Wiki? I'd be _very_ willing to provide you guys _any_ assistance you might need. And even if the users would insist in having 'their own Wiki' (although I think the existing wiki.cocoondev.org is there for _anybody_), I'd be happy in providing hosting for that under the neutral cocoondev.org domain. /Steven -- Dr. Hussayn Dabbous SAXESS Software Design GmbH Neuenhöfer Allee 125 50935 Köln Telefon: +49-221-56011-0 Fax: +49-221-56011-20 E-Mail: [EMAIL PROTECTED] - Please check that your question has not already been answered in the FAQ before posting. http://xml.apache.org/cocoon/faq/index.html To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: newbies documentation (was: Cocoon is too complex for consumption?)
SAXESS - Hussayn Dabbous wrote: The major point is to remember, that the newbies wiki is a part of the cocoon wiki, independent of the underlaying technology, thus coordinating the content, not the technology. Sure. My bias is that people should not go for hunting information, and that a lot, for various audiences, and from various angles, can be found in one place. Thanks for your cooperation! /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 - Please check that your question has not already been answered in the FAQ before posting. http://xml.apache.org/cocoon/faq/index.html To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
