Return-Path: Delivered-To: apmail-xml-cocoon-users-archive@xml.apache.org Received: (qmail 91182 invoked by uid 500); 28 Jan 2003 07:33:41 -0000 Mailing-List: contact cocoon-users-help@xml.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: list-post: Reply-To: cocoon-users@xml.apache.org Delivered-To: mailing list cocoon-users@xml.apache.org Received: (qmail 91118 invoked from network); 28 Jan 2003 07:33:17 -0000 Message-Id: X-Mailer: Novell GroupWise Internet Agent 6.0.2 Date: Tue, 28 Jan 2003 09:33:13 +0200 From: "Derek Hohls" To: Subject: Re: proposal: "The Newbies Competence Center" Mime-Version: 1.0 Content-Type: multipart/alternative; boundary="=_7C23792E.21403AE4" X-MailScanner: Found to be clean X-MailScanner-SpamCheck: not spam, SpamAssassin (score=-0.8, required 9, EMAIL_ATTRIBUTION, SPAM_PHRASE_00_01) X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N --=_7C23792E.21403AE4 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit 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! >>> miles@pcextremist.com 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. To unsubscribe, e-mail: For additional commands, e-mail: -- This message has been scanned for viruses and dangerous content by MailScanner, 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." --=_7C23792E.21403AE4 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit
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!

>>> miles@pcextremist.com 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:     <cocoon-users-unsubscribe@xml.apache.org>
For additional commands, e-mail:   <cocoon-users-help@xml.apache.org>


--
This message has been scanned for viruses and dangerous content by
MailScanner, 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." --=_7C23792E.21403AE4--