Mailing-List: contact dev-help@cocoon.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@cocoon.apache.org
Received-SPF: pass (hermes.apache.org: domain of sebastien.arbogast@gmail.com
 designates 64.233.162.192 as permitted sender)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
        s=beta; d=gmail.com;
        h=received:message-id:date:from:reply-to:to:subject:in-reply-to:mime-version:content-type:content-transfer-encoding:content-disposition:references;
        b=JlkZ9lWYWT22KKqRriM/smE8rlU57iuItdLy4qRZ1AgcEhV1cfkITWoTeAVz2rkIYeYY7gsn2lqcY8NopUopMB+denHx8L62yfnN+qUW08edrBml3/jwEmuXvIjS/Gelm+EDuDID71XNZ3A+Rd35QyJJq+OzGMviuylrFXKagX8=
Message-ID: <a753b7f8050603162284ec6ea@mail.gmail.com>
Date: Fri, 3 Jun 2005 18:22:43 -0500
From: Sebastien Arbogast <sebastien.arbogast@gmail.com>
Reply-To: Sebastien Arbogast <sebastien.arbogast@gmail.com>
To: dev@cocoon.apache.org
Subject: Re: [Docs] A proposed revision, four weeks for Cocoon,
 and a smattering of Julie Andrews
In-Reply-To: <472320D5-86B3-437B-B87D-CB5B71EC17D2@cox.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline
References: <694433862586d3fb40f41a3aaf8b8565@efurbishment.com>
	 <472320D5-86B3-437B-B87D-CB5B71EC17D2@cox.net>

> 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.

Obviously we share exactly the same concerns. I don't know if you had
a look at my documentation workflow proposal
(http://www.planetcocoon.com/node/2079) but as you'll see, everything
is made to put readers needs and assumptions about their knowledge at
the center of our documentation writing process.
And I totally agree with you : current documentation is mainly written
by developers for other developers and that's precisely one of the
main reasons why we started our initiative on Planet Cocoon, to create
a real *user* documentation writing platform.

> 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.

I'm looking forward to hear your ideas. Maybe it could be the occasion
to join our efforts on Planet Cocoon. That's how I joined Mark in this
initiative, you could join us.

> 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.

Once more we'll even do better than that : we are going to setup a
documentation request mechanism so that people can give details about
what they want to know AND what they already know. That way we'll have
an objective view about what we can assume or not when writing
documentation, and eventually make Cocoon more accessible.

> 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.

That would be great !

Cheers
--=20
Sebastien ARBOGAST