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: local policy)
Content-class: urn:content-classes:message
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: quoted-printable
Subject: RE: Planet Cocoon license and reuse of docs
Date: Thu, 26 May 2005 22:05:18 +0200
Message-ID: <329A68716B57D54E8D39FD3F8A4A84DF024C0FDC@um-mail0136.unimaas.nl>
Thread-Topic: Planet Cocoon license and reuse of docs
Thread-Index: AcViFSt761o/IRRATLKqAbXP92O0nQAFX8yw
From: "Linden H van der (MI)" <H.vanderLinden@MI.unimaas.nl>
To: <dev@cocoon.apache.org>

Glen and Ross,

Before duplicating my thoughts in similar replies I want to state this
(replies in random order):

I work in a university department, doing research, so I'm fully aware
what it takes to go through the process of putting an idea in writing
until the moment it is accepted for publication (and by that I mean the
final stage where it should be handed in camera-ready).

I do agree with you on that Glen. Reading your explanation made me
realise I wrote about the CMS as the actor while I meant the persons
using the functionality of the CMS, which is what you wrote. Sorry about
the confusion, but in essence we meant the same.

Ross, you keep hammering on your idea of integrating multiple sources of
documentation by using Forrest. I really don't mind/care what tools are
used to end up with a documentation that is far superior than what we
have now. If it takes Forrest or something that should still be built,
fine by me.
What I don't see right now is the additional sources of documentation AT
THIS STAGE or the near future. In my point of view we better start with
a clean slate in a CMS (or another agreed on tool) and add anything
relevant from another source (whatever that maybe) to the CMS with the
exception of the reference documentation that Upayavira and Ralph or
Reinhard (keep forgetting which one) are working on. IIUC they generate
Javadoc information from the actual code. If that's what you mean Ross
by integrating different sources, then by all means I agree.

Re the general TOC: I have started one about a year ago in the wiki. The
idea was NOT that it would be the ultimate TOC but merely a sort of
catalog of what information is/was available and what is missing. I've
seen other attempts since then with equally valid separations. I would
suggest that you Glen, since you offered it, will have a look at all of
them, from a content POV, not tools POV, and either pick the most
suitable or merge the best from every ideas into something workable. As
Steven has already pointed out: navigation in Daisy can be done/ordered
through queries so anything is possible. And Ross already pointed out
that in Forrest a new/other kind of navigation is also feasible.

Yes it will be a giant task and I'm sure it will not be finished by
those that have started it. The only thing I hope/want to accomplish is
to create enough documentation that it becomes noticed and attracks more
writers.

Let's keep the plan as simple as possible so that the actual writing
gets the most attention. Besides, plans have a tendency to change, so
KISS is in order.

My weekends are horribly crammed with household chores, kids and family,
but I'll see what I can do.

Bye, Helma


> -----Original Message-----
> From: Glen Ezkovich [mailto:glen@hard-bop.com]=20
> Sent: Thursday, 26 May 2005 19:06
> To: dev@cocoon.apache.org
> Subject: Re: Planet Cocoon license and reuse of docs
>=20
>=20
> Helma,
>=20
> I don't want to discourage the effort to create a or deploy a Cocoon =20
> based CMS. I think its important that it gets done. My point is that =20
> no mater how easy and automated the process becomes, good =20
> documentation requires a great deal of human collaborative effort.
>=20
> On May 25, 2005, at 8:30 AM, Linden H van der (MI) wrote:
>=20
> >>> - pick a tool, any tool that meets the criteria I mentioned
> >>>
> >> above and
> >>
> >>> start a new set of documentation there. I suggest Daisy.
> >>>
> >>
> >> What you should be concerned about is managing new and existing
> >> content. This includes some process for accepting vetting, editing/
> >> correcting and publishing.
> >>
> >
> > In short a CMS type of tool
>=20
> LOL I'm a big believer in automation but I think its to much to ask =20
> of a CMS to vet, edit and correct documents. ;-) Let me be clear, a =20
> CMS is an important tool that needs to be in place to help=20
> manage the =20
> process. When a document is submitted someone must read it. Upon =20
> reading it, they make a judgement as to whether it meets some =20
> criteria of acceptability. If deemed acceptable it is then vetted by =20
> "experts". The experts make suggestions concerning content. The =20
> author and her expert collaborators make changes to the content. At =20
> this point an "editor" will examine the document for readability, =20
> spelling and grammar. The editor in collaboration with the author =20
> corrects and improves the document. Once all corrections are made, =20
> the author, experts and editor sign off on it and the document is =20
> formated and published.
>=20
> Until the document is formated what we are dealing with is pure =20
> content. We shouldn't care about layout, formatting, hyperlinks or =20
> anything other then the documents content. It is at this point one =20
> may choose the editor provided by the CMS to convert the source =20
> document, but it is not the only choice. It can be done by hand or =20
> better yet, automated. Once the original document is published the =20
> role of the CMS is to manage and facilitate updates to the document. =20
> It is at this point that an online editor becomes useful for small =20
> changes. Substantial changes are best handled by the same process =20
> that created the original document.  The role of the CMS is to =20
> facilitate this workflow.
>=20
> My argument is not with the need for a CMS but with the=20
> vision of how =20
> it will be used to improve the documentation but providing a simple =20
> single creation and editing entry point.
>=20
> >
> >
> >> Why require a particular tool? Is everyone who contributes code to
> >> Cocoon required to use Eclipse?
> >>
> >
> > Since documentation is best gathered in a CMS, because there will =20
> > likely
> > (hopefully) be more than one person working on it, this inevitably =20
> > means
> > that everyone should use THAT CMS to avoid scattering=20
> documentation =20
> > all
> > over the place (wiki, website, mailing list, blogs, own=20
> websites etc).
>=20
> I don't think a CMS will alleviate this problem. Wikies, websites, =20
> mailing lists, blogs etc. are the most suitable places for=20
> some forms =20
> of documentation. A CMS will allow the fromal Cocoon community to =20
> better manage the content which it owns.
>=20
> >
> >
> >> What if the new document is far superior to the existing=20
> in terms of
> >>
> >
> > Hurray for that. But if you've come up with something that replaces
> > information in other places, do note that in both "origin" and
> > "destination" to avoid others duplicating the effort.
>=20
> Yes, the human element creeps in again. Someone needs to decide that =20
> one document is superior to another and replace the old with=20
> the new. =20
> When such a change occurs the community should be notified as well. =20
> Depreciated documentation is documentation none the less. I believe =20
> the new improved documentation should provide a reference and a link =20
> to the documentation it replaces.
>=20
> >
> >
> >> content and clarity? Who decides this? Do we leave this decision to
> >> the author? Frankly if I'm going to write some documentation, I'm
> >> going to do it because I'm unhappy with what exists and I am likely
> >> to start from scratch or just completely rewrite what exists.
> >>
> >
> > Great! Go ahead. If you feel comfortable enough to write something =20
> > about
> > any aspect of Cocoon, please do. The only thing I ask from reviewers
> > (aka Cocoon committers) is that they read your document and=20
> compare =20
> > what
> > you write to the actual working of Cocoon to see if there are
> > discrepancies that might lead to false=20
> conclusions/understanding from
> > other users.
>=20
> I certainly hope that they would. If they find errors I want to know =20
> about them and correct them. I really should get off may lazy=20
> ass and =20
> do it.
>=20
> >
> >
> >> This is an essential step in producing good documentation.=20
> It is also
> >>
> >
> >
> >> a very time consuming one. Experts are very useful when it comes to
> >> verifying the broad pictures and approaches but to often their
> >> knowledge of the field makes it easy for them to understand the
> >> intention of the author when a newbie will be completely lost.
> >>
> >
> > OTOH If you write down that CForms has a state 'readonly'=20
> when in fact
> > it's 'disabled' that's something Sylvain e.g. will probably notice
> > immediately while it takes trial and error of 'ordinary' users to =20
> > figure
> > out.
>=20
> Certainly. Thats why we need domain experts and documentation =20
> writers. Rarely is one individual superior in both areas.
>=20
> >
> >
> >> Unfortunately this leads to pretty much the same state we
> >> have now, a
> >> lose collection of documents some easy to locate and some buried
> >> deep. Someone needs to manage the documentation. Someone needs to
> >> organize it. While this can be a community effort ultimately
> >> decisions need to made as to where documentation is to be
> >> located and
> >> organized and this needs to be done in a consistent manner.
> >>
> >
> > True, but even the multiple attempts to come up with a general TOC =20
> > have
> > failed so what now? Putting all documentation in one place (at =20
> > least the
> > 'user guide' type which is most needed anyway), following a general
> > structure/TOC is still better than the current state.
>=20
> Yes. Its not so much a general TOC but one that is actively =20
> maintained to reflect the current state of the content. Cocoon is a =20
> dynamic project and as such its documentation needs to be dynamic as =20
> well.
>=20
> >
> >
> >> The issues are different, but of course rules are needed.=20
> With code,
> >> test can be run to verify correctness. Bugs pop up as=20
> others work on
> >> different parts of the code. With documentation decisions need to
> >> made by people as to its value, its understandability and where it
> >> fits in the grand scheme of things. Someone needs to go through it
> >> and insert the appropriate hyperlinks. Random documents no
> >> matter how
> >> informative will not make Cocoon any easier. Its as much about
> >> organization and ease of use from a users point of view as it is
> >> about content and currency.
> >>
> >
> > Ok. Let's sit down then and dream up a general TOC by studying the
> > attempts done earlier.
>=20
> I guess we could learn from their mistakes. ;-) Assuming that the =20
> documentation will grow and change over time, so will the=20
> TOC. On the =20
> other hand, if you view the TOC as a model of Cocoon's documentation =20
> we can at least have a starting point for our first documentation =20
> sprint. I think this is worthy of some more discussion. I have some =20
> free time this weekend (I hope) and will sit down and look at the =20
> documentation. I think its worth while to expend some effort in =20
> charting a course for Cocoon's documentation. The one thing I know I =20
> would like to see is the syncing of documentation with development. =20
> This would be a gargantuan effort because there are many small =20
> changes that occur with each release, but I believe the benefit to =20
> users and developers would be worth the effort.
>=20
> Lets examine the current documentation, develop a vision for its =20
> future and actually work towards achieving that vision. I am willing =20
> to commit to participating in the effort to both develop the=20
> plan and =20
> to implement it.
>=20
> I've always thought we needed an XD to complement XP. Lets find out =20
> if it will work.
>=20
>=20
> Glen Ezkovich
> HardBop Consulting
> glen at hard-bop.com
>=20
>=20
>=20
> A Proverb for Paranoids:
> "If they can get you asking the wrong questions, they don't have to =20
> worry about answers."
> - Thomas Pynchon Gravity's Rainbow
>=20
>=20