CC:ing this to cocoon-docs because that's where it should go :)
On Mon, 27 Jan 2003, SAXESS - Hussayn Dabbous wrote: > hy, everyone > > It's time to round up i think. I have taken all the > emails from today and some from yesterday dealing with > this theme and extracted all information therein. > The following summary therefore contains snippets of > many people. I did some editing though to get things > into one document. Hopefully i didn't miss too much. > But you are invited to complete this roundup, if you > feel there is something missing. > > The next steps should be : "clearification, decision" > > happy reading > > hussayn > > -------------------------------------------- > Proposal for the "Newbies Competence Center" > -------------------------------------------- > > I. The problem statement > ======================== > > "Users can not get quickly started with Cocoon" > > probable Causes: > > 1. The existing Cocoon documentation is poorly written > 2. The existing Cocoon documentation is poorly structured > 3. There are gaps in the existing Cocoon documentation > 4. Some of the existing Cocoon documentation is located > in more than one site > 5. ...(other issues related to installation/file size etc etc) > > > I. The goal of the "Newbies Competence Center" > ============================================== > > There is need to create documentation for people, who > are new to cocoon and want to try their first steps > in this technology. Some thoughts have been written > down in the cocoon-users mailing list. > The goal of this effort is to create a well defined, self > contained source of reliable information for Cocoon newbies, > along the lines of > "how to setup Cocoon in 15 minutes" and > "HOWTO setup your intranet with XML in 1 day". > The effort shall keep as tight as possible with the > already existing cocoon infrastructure and shall be > coordinated with the ongoing efforts on the cocoon core > documentation. > > > II. The requirements > ==================== > > general remark: > There are severe doubts in creating a new documentation platform, > namely a new wiki site or a new documentation portal or whatever > disperses from the existing infrastructure. On the other hand the > existing infrastructure needs additional work in order to fit for > the requirements mentioned in the following list. > > The most important requirements are: > > 2.1 MUST allow users to comment/improve the docs online to make > it as easy as possible > > 2.2 MUST clearly identify these docs as being "for beginners" and > "reviewed by an editor of the Cocoon team" to prevent beginners > from getting lost in obsolete/unreliable docs. This could be > achieved by labeling the pages, using different layouts, colors, > etc. > > 2.3 SHOULD make these docs and their comments searchable, separately > from the technical and/or unchecked existing docs to prevent > beginners from being overwhelmed with irrelevant search results. > > 2.4 MUST allow all docs to be searchable simultaneously, to prevent > users from having to search in X different places for info. > > 2.5 SHOULD if ever possible be integrated with existing Cocoon > community tools (documentation pages, cocoon wiki) to avoid > fragmentation of skills and resources > > 2.6 MUST provide constant "editors effort" to keep the documentation > set correlated, cleanly structured and up to date. > > > III. Additional thoughts > ======================== > > o have a look at http://wiki.cocoondev.org/, you'll see a very > prominent link to a currently unexisting Main page for this > 'NewbiesGuide'. Could be populated instantly. > > o It was discussed, if the newbies documentation effort shall take > place within the cocoon core documentation team or coordinated > with that team and deveoped in parallel. > > o There was an idea to redesign the cocoon documentation entry page > and provide chapters like: > > 1) First steps > 2) User's Manual > 3) User's Reference > 4) Architecture > 5) Developer's Guide > > This could basically be achieved by reorganising existing > documentation. > > o The complete cocoon documentation including the > "Newbies Competence Center" should be self contained, > published by cocoon itself and included into the distribution, > or set up as a separate documentation set, which can > be downloaded and integrated into cocoon webapp for online publishing. > > o We need to be crystal clear and display on each page exactly > > - who the target audience is > - what we assume of them in terms of background, knowledge and skills > > We possibly can add pointers to XSLT, basics of XML and give them > some tips as to get up to speed ASAP. > > o Another more visionary idea was: > > What about having > > - the cocoon documentation set for distribution > . manual pages > . possibly pdf for printout version > - the cocoon online site > including online access to the docs (multiple versions > of course, difference viewer as option) > - the cocoon documentation playground (wikipages) > - access to other related sites, bookstores, > this mailing list, commercial project enabler, ... > > All of this tied together by the sunshine portal, or > jetspeed, or whatever.... > Give it a newbies view, an experts view, a developers view, > a personal view.... > > o It is appreciated to use the existing wiki, mailing lists, CVS and > the existing web site, the idea being that the community can > concentrate on these three "tools" and not have a different tool > for each goal. > > o Introduce something driven by "metadata", maybe simply adding > some name-value pairs at the end of the wiki text, e.g: > > - TARGET-AUDIENCE: beginners > - REVIEWED-BY: [EMAIL PROTECTED], Tuesday January 28th, 2003 > - COCOON-RELEASES: 2.0.1, 2.0.4 > > Which might be enough by itself by the way, but if this could > translate to cool-looking icons or different page backgrounds on > the wiki it would be very nice, and maybe not that hard to hack. > JSPWiki supports plugins, so maybe there is an easy way. > > o How about adding a tab structure/frameset that toggles between > Wiki editing of the page and a metadata view. Using > Dublin Core's core elements, it makes it easy to create a > flexible form. The form consist of a toolbar containing a save > button and three dropdowns for the 3 DC categories > (Content, Intellectual Property, Instantiation). > The *.dcxml file is used to populate the form if it exists. > If new or adding an element, the user selects from the dropdown and > JavaScript writes a new row containing that metadata item. > Save puts it in the central location. > > o 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. > > > -- > 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]> > > --------------------------------------------------------------------- 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]>
