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.
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".
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.
Please remember that neither of the efforts I am discussing are in any
way official, or representative of the views of the Cocoon PMC.
You are quite right: it's about knowing your audience. I am looking
forward to hearing what you and others have to say!
Regards,
Mark
Mark, I applaud your efforts to improve Cocoon's documentation and I
am thankful for your company footing the bill. However, I think what
you have written above just continues the existing problem with a
different set of words. The two paragraphs as a whole assume
familiaraity with the concepts of MVC, separation of concerns, that
Cocoon has a sitemap and what that is, pipelines, generation,
transformation and serialization and continuation-based scripting. If
I were completely unfamiliar with Cocoon, I really still would not
know what it is other then a web application framework.
I spent last weekend going over Cocoon's documentation, various
threads concerning it and proposed TOCs. I came away with the feeling
that Cocoon's documentation is written by experienced Cocoon
developers for experienced Cocoon developers. The only thing Cocoon's
documentation should assume is that a user is familiar with XML and
XSLT. If they want to use flow the documentation needs to assume that
they have some familiarity with javascript and/or Java. Its similar
for each aspect of Cocoon. Assume only enough to go forward with out
having to explain things outside of Cocoon.
I have an email that I have been working on since Monday with an
outline of how I was planing to proceed with writing new
documentation. Key aspects are that we need to have separate
documentation for users and developers and that the user documentation
needs to assume as little as possible about the users experience.
Hopefully, I will edit down to a few paragraphs and send it this
weekend.
In the meantime you might want to consider targeting your
documentation for the most junior and least skilled website developer
in your company. Better yet, a 1st year student.
I mean all this in the most constructive way. Hopefully we will be
able to collaborate over the next 4 weeks and get a good start on
rewriting these docs.
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
