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 skounis@gmail.com designates
 64.233.170.201 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=R/rol4Cac4sLp9v8g1IpiFu9LHgAgqEd3VE4i3HKHfZ/YvXqJBiZRizOzCXgTmFunToKfb5bsHCNX5/IHqoQVYAytkF1ytdTLrhAQlvr7Psqbqu4C+h1PPbtxuah2iNqvnJLe20EWyoi8fDx8YxI2/7jW59+n8MpsmI0ilej6CA=
Message-ID: <f4e3488b0505250336518bca8c@mail.gmail.com>
Date: Wed, 25 May 2005 13:36:52 +0300
From: Stavros Kounis <skounis@gmail.com>
Reply-To: Stavros Kounis <skounis@gmail.com>
To: dev@cocoon.apache.org
Subject: Re: Planet Cocoon license and reuse of docs
In-Reply-To: <329A68716B57D54E8D39FD3F8A4A84DF01AAF606@um-mail0136.unimaas.nl>
Mime-Version: 1.0
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline
References: <329A68716B57D54E8D39FD3F8A4A84DF01AAF606@um-mail0136.unimaas.nl>

i totally agree with you Helma. the content is that matter.

I think that they are many people around here that can do the dirty
job to create well formed
files (xml, xhtml, etc) but few that can write documentation.

I don't have check yet what you have do until know with Steven/Daisy
but even wiki is enough if someone want to "produce" content.

Of course I'm not against anyone that want to develop a full featured
"doc" system.

regards
--stavros

On 5/25/05, Linden H van der (MI) <H.vanderLinden@mi.unimaas.nl> wrote:
> Guys,
>=20
> with all due respect for the various efforts to improve the
> documentation, there is only one way to improvement and that is
> screening all the available documentation on validity and clarity and
> rewrite/enhance it when it's lacking or write the missing pieces. This
> screening process is something that HAS to be done by hand, there is
> nothing to automate about.
> If you want people to participate in this tedious but very important job
> the only tools you need is some kind of repository for the "new"
> documentation, a (team of) editor(s) that supervise the work and decide
> on the quality of the content and the organisation of it and, most of
> all, EASY and QUICK access to an editor that produces the documentation
> in an acceptable form.
>=20
> Don't bother writing YANDT (Yet Another Nifty Documentation Tool) but
> look at what's available and use THAT. If all the time spent on writing
> posts here ABOUT the documentation had instead been spent on WRITING
> documentation, we would have had the best documented project on the
> planet.
>=20
> I look at all this from a documentation writer's point of view and I
> repeat what I've said before: give me easy tools that produce documents
> in a format that can easily be transformed into anything you guys dream
> up to be handy, but most of all don't take ages to setup/startup and
> don't need a 50-page user manual.
>=20
> For now the only thing I've found that meets MY criteria is Daisy and
> since Steven has already granted me some workspace I've started there.
> True, this will not be the ultimate destination and yes, it might have
> some drawbacks, but it works!
>=20
> Let me propose an entirely different strategy:
>=20
> - pick a tool, any tool that meets the criteria I mentioned above and
> start a new set of documentation there. I suggest Daisy.
>=20
> - everyone who wants to write documentation should use THAT tool, that
> repository to write his or her document. Let's call this person a
> writer. Before doing the actual writing we ask the writer to verify if
> there is nothing on his topic in either wiki or 'official
> documentation'. If there is, the writer should use the information there
> and add it to the document.
>=20
> - there are several committers that are also concerned about the
> documentation and make themselves heard in every thread about the topic.
> You guys know the code best and each probably has his own field of
> expertise.
> What I would suggest is that you volunteer to be editor/reviewer in your
> field of expertise. Your task in the documentation project will be to
> review. So, the document written by a 'writer' is reviewed to see if the
> document is valid (i.e. the information is correct and current). If you
> feel something is missing you can either add it yourself of mark it for
> the original writer to add (based on time constraints). When both of you
> agree on the document it goes 'public', i.e. visible/usable for the rest
> of the community.
>=20
> When a document goes public and it includes information from the wiki
> and/or the 'official documentation' the editor replaces those pages with
> a link to the new document.
>=20
>=20
> I know in an open source community there are not much 'rules' to be
> enforced, but if you can set up rules for committing code, you might as
> well set up rules for committing documentation.
>=20
>=20
> just my 2 ct.
>=20
> Bye, Helma
>=20
>=20
>=20
>=20
> > -----Original Message-----
> > From: Ross Gardler [mailto:rgardler@apache.org]
> > Sent: Wednesday, 25 May, 2005 01:11
> > To: dev@cocoon.apache.org
> > Subject: Re: Planet Cocoon license and reuse of docs
> >
> >
> > Upayavira wrote:
> > > Antonio Gallardo wrote:
> >
> > ...
> >
> > >> With the new apache zones, I think there is posible in a rasonable
> > >> amount of time (hours?) to setup a CMS to do the job.
> > >>
> > >> WDYT?
> > >
> > >
> > > Then someone should do it, and we will see where that takes us. I'll
> > > volunteer for the part of doing any document conversions
> > that might be
> > > required.
> >
> > I intend to do some experimentation over at Forrest with Daisy as the
> > CMS once we have Forrest 0.7 released (very soon now).
> >
> > In the meantime, I will continue to work with PlanetCocoon and other
> > such initiatives (the Wiki for exmample) to allow any content they
> > create to be incorporated into the Cocoon docs, and to provide a link
> > back to the relevant "host" CMS.
> >
> > When we have a working demo the Cocoon community can decide
> > if they want
> > to use it.
> >
> > Ross
> >
>=20


--=20
Stavros Kounis                        Osmosis networks & consulting
http://tools.osmosis.gr/blog          http://www.osmosis.gr