Hy;
as a newbie (of three months age ;) ) i'd like to
contribute my thoughts to the documentation area:
1.) From my now 20 years experience in "computer art" i
learned that the newbies can tell much more about the
features of a program, than the developers can. Why?
because the newbie always tries "the wrong pathes" through
the software therefore detect the weaknesses and strenghts
of the app and often walk through pathes the developers
never thought of inventing new use cases , etc.
In turn the developers always are biased from their
architectural insights...
2.) In several projects i was faced with the situation of
lacking or inappropriate "user documentation". One
strategy for improvement was always to let the users
start writing down what they think the app does and
how they would use it. Then the developers had the
time to start thinking over what they implemented.
This is an iterative approach that fits better to the
real world, than "smacking at the developers and force
them to start documenting" ...
My *personal* conclusions on this:
1.) Instead of shouting against the developers i started
writing down my experiences within my company wiki.
I did this because i wanted a clear separation from
all the "masters of the art" articles turning up in the
cocoon wiki. Besides this some of the points i tackled
have to give at least little insight into tomcat and
other loosely coupled themes which i didn't want to add
to the ever growing cocoon wiki.
2.) Whoever writes docs for the newbies MUST get
help from an experienced user or a developer at least
for review. This could be the start of a productive
user centric quality assurance. This may eventually
get all these very interesting but (sorry) unneaded
explanations of avalon and other base technologies
out of the docs or at least into separated docs.
3.) Writing docs MUST be made as simple as possible. But it
should be surveyed from one or a few "editors" who keep
the docs in right shape, and right organisation.
so i would propose (as Derek does):
1.) Provide a platform separate from the already existing
documentation areas, which is clearly labeled as the
"newbies competence center", accessible to everyone
with most ease (start getting productive in a minute)
2.) I would recommend to use a separate Wiki for this
purpose.
3.) Instead of letting such a wiki free floating, get
at least one person into the role of
the "responsible editor"
And despite any possibly upcoming thoughts like
"this is open source, everyone (thus noone?) is responsible"
i would gladly get into the role of the "responsible editor"
for some time at least. And if it makes sense, i also would
start hosting such a "cocoon CC Wiki".
Meanwhile i will continue writing down my personal insights
and eventually donate all this stuff to whatever
will come up as a newbies documentation infrastructure ...
regards, hussayn
Derek Hohls wrote:
Tony
In case you missed my other wandering thought pattern; its my
strong feeling we need a SINGLE section of the website -
preferably one well-insulated from the ramblings on the other site
which is "always under construction" that (including any
formal guides) solely addresses ONLY the needs of newbies and
has ALL the documents AND faqs AND minimal downloads AND simple
sitemaps etc in ONE place - no obscure wikis/mailing list links.
(Gee, we are working with a web publishing platform here - how hard
can this be to put together *technically*?? ) The trick is writing good,
clear, simple pages - and that's a matter of write - read - edit ....
recycle until your target newbie - not your average
developer/contributor -
can make sense of it...
Derek
>>> [EMAIL PROTECTED] 27/01/2003 06:29:12 >>>
In light of this ginormous thread, do we need more newbie guides to
getting started with Cocoon? Obviously the CTWIG or whatever is out of
date, so perhaps there's a demand for something like a Busy Developer's
Guide to getting started with Cocoon? I'd be more that willing to write
stuff up that for direct inclusion with the Cocoon documentation that is
distributed with the releases.
If so, I'll start writing up a Cocoon BDG (or even a series) in Document
1.1 format.
P.S. Docs team: Perhaps it's time to start assimilating Wiki content into
the distribution docs?
Tony
--
Cocoon: Internet Glue (A Cocoon Weblog)
http://manero.org/weblog/
---------------------------------------------------------------------
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* <http://www.mailscanner.info/>, 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."
--
Dr. Hussayn Dabbous
SAXESS Software Design GmbH
Neuenhöfer Allee 125
50935 Köln
Telefon: +49-221-56011-0
Fax: +49-221-56011-20
E-Mail: [EMAIL PROTECTED]
---------------------------------------------------------------------
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]>
