Niclas
What you say makes sense - I think the Wiki has a high value in
"ease of use" for the documenters (that's ALL of us, BTW) to create
and edit documents - then at some point "the editor" (whoever that
is)
needs to pull out the best, structure them, and "submit it to
cocoon-dev"
(whatever that means....?)
Only once there is a "bare minumum" for the newbie documentation
set available should the cocoon site be chnaged the way you
propose.
And I would suggest a
1) Start Here!
rather than the jargon of : "1) Newbie's Guide to Killer App."
but, yes, this principle of a single, simple first page to choose
from makes sense.
Side Note and Rant
We need to be crystal clear at the first point on each entry page
just
exaclty who the target audience is and what we assume of them of them
in terms of background, knowledge and skills - and if they have to
learn
some XSLT or understand basics of XML then we say that and give them
some tips as to get up to speed ASAP. If they do not know any of
that,
then hopefully they still come back to Cocoon once they get some idea of
where it might fit into their universe BUT at the very least they should be
tempted to do the quick download and run the "hello world"
demo....
Derek
>>> [EMAIL PROTECTED] 27/01/2003 11:43:09 >>>
On Monday 27 January 2003 17:14, Bertrand Delacretaz wrote:
> Hi Hussayn,
>
> I mostly agree with your point of view, except on the "separate wiki"
> thing. (And by the way, thanks a lot for your "less talking, more doing"
> approach!)
>
> What worries me *a lot* with starting yet another documentation site is
> the dispersion of resources - wouldn't it be much more efficient to have
> you, Derek and possibly others joing the (mythical) Cocoon docs team
> with the aim of creating these newbies docs?
>
> See also http://wiki.cocoondev.org/Wiki.jsp?page=CocoonDocsPlan, I think
> your concept can fit nicely into this.
>
> I'm convinced that it is possible to create the "newbies competence
> center" that you mention *inside* the existing wiki - a well-designed
> start page and navigation should help newbies find their way.
Maybe I am a real idiot, but shouldn't the Cocoon Documentation be published
by Cocoon (it IS a publishing framework) itself upon installation??? This
already happens, but we all agree it falls short to point the newcomer in the
right direction. But still, the pointer must be where the newcomer looks
first, among the docs that come with the download (or am I the only one
starting there?).
Wiki is fine for "loose" and quickly changing documents, somewhere between
Stefano's (and others) "Random Thoughts" on mailing lists and proper
documentation efforts.
If Hussyan, Derek and whoelse are really serious about this (which we ALL pray
they are), crank up the first XML doc, submit it to cocoon-dev, and you have
committer status in no time, because;
1. Developers hate to apply patches and files submitted by email.
2. Developers LOVE people dedicated to documentation.
And this is especially true on cocoon-dev ;o)
So, what I suggest, is a new "first page" of Cocoon, which basically is a
level above the current one, and spawns off into 4-6 lower levels, depending
on the users background and interest;
1) Newbie's Guide to Killer App.
2) User's Manual
3) User's Reference
4) Architecture
5) Developer's Guide to Killer App.
Or something like that.
My 0.02 ringgit, about 0.5 cent.
Niclas
---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faq/index.html>
To unsubscribe, e-mail: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>
--
This message has been scanned for viruses and dangerous content by
MailScanner, and is believed to be clean.
"The CSIR exercises no editorial control over E-mail messages and/or
attachments thereto/links referred to therein originating in the
organisation and the views in this message/attachments thereto are
therefore not necessarily those of the CSIR and/or its employees.
The sender of this e-mail is, moreover, in terms of the CSIR's Conditions
of Service, subject to compliance with the CSIR's internal E-mail and
Internet Policy."
