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) <[EMAIL PROTECTED]> 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:[EMAIL PROTECTED] > > Sent: Wednesday, 25 May, 2005 01:11 > > To: [email protected] > > 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
