Mark,
On Jun 4, 2005, at 12:05 AM, Mark Leicester wrote:
Hello Glen,
Thanks for your comments! They are indeed constructive, and you are
right to raise this issue. Who are we writing for? In simplistic
terms I imagine two groups: fairly-technical and not-so-technical.
My solution has been to create one site, http://
www.spreadcocoon.com, for the not-so-technical market, and another,
http://www.planetcocoon.com, for the fairly-technical market.
Spread Cocoon is modelled on http://spreadfirefox.com. It's for
people who want to know about Cocoon, want to know how it can help
them, want to hear success stories, see example sites, know about
Cocoon events, and generally buy badges, posters, stickers and T-
shirts. On the other hand, Planet Cocoon is a rich developer
community site where technical people can find the nuts and bolts,
and get on with being creative. Firefox has similarly separated
sites, and I believe the same two-pronged approach may work for
Cocoon.
We are talking about two different things here. An evangelical site
is not the same as a novice site. When we talk about Cocoon users we
are still talking about developers. This most certainly isn't the
case with Firefox users. What I see as the problem, is that the
current documentation assumes a familiarity with both the theories
that led to the development of Cocoon and to some extent Cocoon
itself. (you can find the explanations, but then you get taken off
the path which you were previously following [1]) Someone new to web
development would have a hard time understanding the documentation.
Even experienced developers who were working within a different
framework would have some difficulty in understanding the usefulness
and purpose of Cocoon and some of the various pipeline components.
Its been repeated in several threads concerning documentation and
marketing that Cocoon appears as some huge scary beast. While its
true that the Cocoon distribution has many components and multiple
ways of accomplishing similar tasks, even the most complex pipeline
is pretty simple when compared to a JSP that performs the same tasks.
The documentation should show how simple its to gather data from
various sources and present it to users (human and computer) in
multiple yet consistent ways.
In order to convince developers that Cocoon is both simple and
powerful the documentation needs to consider both the novice and the
experienced developer. That means that explanatory text needs to
assume only minimum knowledge of web development technologies and
theories employed by Cocoon. In order to be accessible to novices
simple examples need to be given. In order to be of value to
experienced developers use cases need to be presented and realistic
examples which solve the problem should be provided. Along with all
of this the documentation needs to also serve as a reference so that
a developer can quickly and easily find the information they need.
That said, there is room for other types of documentation. i.e.
tutorials, recipes, etc. that target various levels of skill. The
main point is that when a user, novice or expert, looks in the main
set of documentation, they find something that at least explains and
demonstrates the aspect of Cocoon in which they are interested, in
such a way that both are satisfied. The one thing I hate is a trivial
example that does not scale as the problem gets slightly more
complex. What I used to hate was an example that was more complex
then I could understand.
This text is targeted at Planet Cocoon: experienced developers,
wanting to know more, perhaps weighing up Cocoon as a possible
solution alongside other web application frameworks. Let's get this
text right for developers. We can tailor it further for different
types of developers, like "Click here if you want to compare Cocoon
with Struts", "Click here if you want to compare Cocoon with .NET",
"Click here if you are a 1st year student who wants to change the
world".
Thats fine. It will allow them to compare Cocoon to other frameworks
or become more involved with the Cocoon community. What it won't do
is explain the concepts.
For the equivalent high-level paragraphs on Spread Cocoon, I can
imagine wholly different language oriented to the non-technical
public. Let's develop a version of this text for the general,
thrill-seeking, public.
OK, do you know of anyone who accesses a cocoon driven site and who
is not a developer and who cares that the site is built on Cocoon?
Anyone who is going to access a site devoted to Cocoon, is most
likely a developer.
Please remember that neither of the efforts I am discussing are in
any way official, or representative of the views of the Cocoon PMC.
I remember. I'm not that old that my short term memory is shot.
(close but not yet) :-)
You are quite right: it's about knowing your audience. I am looking
forward to hearing what you and others have to say!
I'm not going to say as much as I planed. I'm working on keeping my
mouth shut. Seriously, I want to get started on improving the
documentation. I'll be sending an email outlining the direction in
which I'll be heading. Unfortunately, I won't be getting paid to work
on this so the time frame is a bit of a question.
[1] http://cocoon.apache.org/2.1/userdocs/index.html takes you to
http://cocoon.apache.org/2.1/userdocs/concepts/index.html from which
you must go back to user documentation to continue.
Glen Ezkovich
HardBop Consulting
glen at hard-bop.com
A Proverb for Paranoids:
"If they can get you asking the wrong questions, they don't have to
worry about answers."
- Thomas Pynchon Gravity's Rainbow
