I don't think that the word "newbie" is such a stigma. People know when they are newbies and not. Rarely do people take it offensively unless its an outside person telling them that they are a newbie. In fact people can take it tongue in cheek as the "for Dummies" or "Idiots guide to ... " books show. Despite their tongue in cheek titles they are amazingly popular. However, the documentation we are proposing is not just targeted at newbies but eventually will span the spectrum of users. For this reason I think the title you proposed is the right one. As to using Wiki, I never have but I will state that id like the documentation to actually be served by cocoon. The benefits to that is the multi-content publishing framework at its best. Users can get PDFs or post script or any number of other types of content as well as the surfed content.
What I would like to see now is a style guide for XML documents that will be common to all published cocoon info. In this manner we can apply a standard XSLT transform to all documents and the writers would just be using XML to accomplish the task. This would give us allot of flexibility. What I am talking about is a custom schema (or borrowed one) that all of the documentation authors can validate against and that the template authors can use to transform. Then I would suggest that the full cocoon samples and documentation be put through this framework. It would take some thought because you want the ability to have it referencable and indexable. For example, I should be able to create a sitemap entry that will combine all cocoon docs into one big page and transform it into PDF. Its always best if you start with architecture and start filling things in. -- Robert ----- Original Message ----- From: "SAXESS - Hussayn Dabbous" <[EMAIL PROTECTED]> To: <[EMAIL PROTECTED]> Sent: Tuesday, January 28, 2003 11:48 AM Subject: Re: proposal: "The Newbies Competence Center" > seems as if my round up generqted even more input ;-) > thanks to all of you. > > so what do we have now? i reround up here: > > 1.) there is a strong push towards "role based" documentation > 2.) there is a strong recommendation to use cocoon-wiki > 3.) the discussion roles on over the whole documentation set > > hmm... seems so as if this gets a bigger task, than expected ;-) > > by the way, i looked up the word "newbie". It may be of interst, > that this is the short from of "new boy". Hey, we can't do that ... > > I'd recommend to rename this to "The Cocoon Competence Center" > and start with the "beginners" section on the cocoon wiki... > > any doubts ? > > regards, Hussayn > > > Derek Hohls wrote: > > This is getting periously close to documentation ;-) > > Seriously, this is the kind of description that is incredibly > > useful to have up front - never mind arguing over who should > > have what skills and how they should work together ... that > > is a project/company issue and will differ from case-case > > (the current view is that most people are multi-skilled anyway) > > BUT we can all agree on what skills are needed to work > > with Cocoon and can link our documentation (see other mail > > on wiki classifications) to those skills; what Peter elsewhere > > has called "role based documentation". > > > > It will be of great help to the new user to see what he/she might > > be expected to know (or learn) before getting up in the > > intricacies of sitemaps, generators and the rest of the jargon! > > > > >>> [EMAIL PROTECTED] 27/01/2003 11:59:41 >>> > > Tony Collen wrote: > > > > >For instance, with a typical installation of Cocoon, we could define the > > >following roles: > > > > > > - Content Creator. This person authors XML for the site to be > > >transformed. This role works when most of the content is static. > > >However, if a lot of the data is being pulled out of a database, they > > >would be in charge of something like data entry into the database, etc. > > > > > > > I've been seeing this role work out well in practice. There is > > grumbling when they can't mark up their content significantly like they > > used to in Frontpage or Dreamweaver, but after seeing a demo, they > > usually acquiesce. > > > > > - Graphic/Web designer. This person is in charge of the style of > > >the site. Not only do they come up with how the site looks through the > > >design of the final HTML, but they also write the XSL to transform the > > >content into the desired format. Sometimes this person is also the > > >content creator. > > > > > > > This role, however, falls apart quickly. There are three roles here and > > it's rare that any one person satisfies all of the roles successfully. > > > > 1) The graphic designer: > > The artist/production manager who is a whiz with Photoshop/Paint > > Shop Pro/The GIMP. They design the overall look and feel for the site. > > Anyone who has seen a good graphic artist can attest to the fact that > > not everyone can do the job. > > > > 2) The HTML/CSS web monkey (term of endearment -- not meant to offend): > > Can take the layout design from the graphic artist and turn it into > > clean and useable HTML/CSS markup. Frontpage et al are useless in this > > regard. > > > > 3) The XSLT author: > > Transforms the internal XML document to the web monkey's HTML > > model. This role is commonly found in the engineering department and is > > needed for the non-presentational transformations that occur quite often > > in Cocoon as well. > > > > In my opinion, it is by far the greatest amount of work in site > > production in terms of getting off the ground. > > > > > - Administrator. In charge of the servlet container, and > > >modifying the main sitemap. Monitors logs, and able to identify > > >when a component would need to be cacheable, poolable, etc. Sometimes > > >this role can further be separated out into servlet container admin and > > >sitemap admin. > > > > > > > Developers too often need to edit the sitemap for this. The > > Administrator definitely deals with installing software packages (would > > be in charge of installing blocks for example) and maintaining the > > servlet container/EJB container. But the sitemap is definitely drifting > > into the lead developer's domain with subsitemaps handled by subproject > > leads. Could you imagine asking a sysadmin to switch the cinclude > > transformer to a non-caching variety on URL pattern X? I can, however, > > see a lead developer editing the sitemap locally on a development box > > and asking the sysadmin to upload the changes. > > > > > - Programmer. I think this is what we now call "developer" -- > > >this person is capable of developing custom components, e.g. Generators, > > >XSPs, etc. This person might also code the Flow layer logic. But maybe > > >not. > > > > > > > And this person would definitely need to have access to a sitemap for > > testing and deployment. They can't work in a bubble. New generators > > and XSPs go hand in hand with at least one new URL pattern in the sitemap. > > > > >Ideally, all of these roles work together in order to get things done, but > > >they only have to worry about their specific role. > > > > > > > I have come to believe this is a fairy tale. No individual in a > > development group, in my opinion, can *ever* worry about just their > > role. They can specialize on their role, but you can't make a rigid > > wall here. Maybe as Cocoon (and more specifically, Cocoon's best > > practices) matures, this may get better. > > > > What Cocoon has done is allow each role to define their contracts with > > which to work with each other. The content authors always make > > documents according to a particular schema (although more likely, they > > are filling in a web form or using some standalone data entry client), > > and no matter how the layout or storage method changes, their work is > > safe. Their schema is their contract. The programmer puts the content > > away and retrieves in again. They respect the content author's contract > > (usually they defined the contract) and can switch datastores, > > versioning, access points, etc. without disturbing the way the content > > authors work. The presentation group takes the content made by the > > content authors and made available by the programmers (and/or site > > administrator) and is assured of their result because they know their > > inputs -- the contracts -- are defined. > > > > This is not the same as ignorance of each others' roles in a working > > group. This is simply allowing each to easily work in parallel without > > stepping on each others' toes. The day that each group only worries > > about their role and no one else's is the day that communication stops > > and things start to suffer. Cocoon allows these concerns to be > > separated so that while people can negotiate their contracts (to coin a > > phrase), there is no point to a content author getting into the details > > of a generator. Their contract is fulfilled when they write their > > content. It works because it's *harder* in Cocoon to find justification > > to step on someone else's work, but that doesn't mean, for example, that > > a programmer can't be interested in what the designer is making or help > > in design work. It just means that the artistically gifted programmer > > starts working with a different contract in mind. > > > > With JSPs, you only had self-control and discipline to maintain the > > contracts (assuming the contracts were adopted in the first place). > > Cocoon is simply codifying it: making the right thing easier to do than > > the wrong thing. > > > > >Now that we have defined roles, its easy to classify the documentation we > > >have now. Obviously, the content creator doesn't have to worry about > > >performance issues, so perhaps that info would go into the Administrator > > >section. Likewise for information about logging. Conversely, people > > >writing a custom generator obviously fall into the Programmer category, > > >and they would probably know not to have to stumble into the > > >"Administrator" section. > > > > > > > A content creator wouldn't have to know, but everyone else would. > > Profiling XSLT, efficient generators, DOM vs. SAX in your components, > > making your component cacheable, store settings. These are all > > performance related but they aren't all the domain of the administrator. > > > > >To sum up, Cocoon was developed with SoC in mind. IMHO, the current > > >documentation managed to comingle the concerns, so we ended up with 4 or 5 > > >different places that something could go. If we mirror the SoC model in > > >the documentation, I think we'll end up with some successful and useful > > >docs. > > > > > > > I think this is a bad idea for the reasons stated above. > > > > Since it's Super Bowl season here in the U.S., I'll use a (American) > > football analogy. Before Cocoon, in the heady days of just JSP, ASP, > > and PHP, it was a pickup game at the park. The role of quarterback is > > constantly changing who it applies to and everyone's scrambling in all > > different directions. People generally enjoy themselves and are hostile > > to the idea that people should be assigned roles and stick with them. > > Then another group of people comes by that wants to join in the game. > > No one knows each other and there are a lot more fumbles and people are > > more likely to get hurt because they don't know the rules to the game. > > > > Cocoon is getting closer to league play where people get on the team as > > a quarterback or as a center or as a wide receiver. The have a > > particular role and they serve that role well, but they need to know > > what the other folks are doing. They need to have flexibility and be > > able to adapt to the other roles when the need arises. > > > > These are, of course, my opinion on the matter. > > > > - Miles > > > > > > > > --------------------------------------------------------------------- > > 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 E-mail messages and/or > > attachments thereto/links referred to therein originating in the > > organisation and the views in this message/attachments thereto are > > therefore not necessarily those of the CSIR and/or its employees. > > The sender of this e-mail is, moreover, in terms of the CSIR's Conditions > > of Service, subject to compliance with the CSIR's internal E-mail and > > Internet Policy." > > -- > 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]>
