cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stavros Kounis <skou...@gmail.com>
Subject Re: Planet Cocoon license and reuse of docs
Date Wed, 25 May 2005 10:36:52 GMT
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,
> 
> 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.
> 
> 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.
> 
> 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.
> 
> 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!
> 
> Let me propose an entirely different strategy:
> 
> - pick a tool, any tool that meets the criteria I mentioned above and
> start a new set of documentation there. I suggest Daisy.
> 
> - 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.
> 
> - 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.
> 
> 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.
> 
> 
> 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.
> 
> 
> just my 2 ct.
> 
> Bye, Helma
> 
> 
> 
> 
> > -----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
> >
> 


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

Mime
View raw message