cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Derek Hohls" <DHo...@csir.co.za>
Subject Re: newbies documentation (was: Cocoon is too complex for consumption?)
Date Mon, 27 Jan 2003 09:12:58 GMT
A quick addition to what Hussayn suggests - which is well 
explained and makes perfect sense - is to take this one step
further - lets have a wiki for people to add/suggest etc BUT
we need to take from it the most polished and relevant material
and make it into a formal and well laid-out website (yes, I do
use wikis and I do host one inside my company - but they are
not always very accessible or well-structured from a newbie
point-of-view) - if we do our design correctly ;-) this should not
require much more than a stylesheet or two for the conversion.
 
Maybe the first topic on the Cocoon Newbie Wiki could be :
"Framework for a Cocoon Newbie Web (non-wiki) Site"??
 
I second Hussayn as editor for the new site (wow, a *real*
volunteer)

Derek

>>> dabbous@saxess.com 27/01/2003 10:52:47 >>>
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
> 
>  >>> tcollen@neuagency.com 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:    
<cocoon-users-unsubscribe@xml.apache.org>
> For additional commands, e-mail:  
<cocoon-users-help@xml.apache.org>
> 
> 
> -- 
> 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:  dabbous@saxess.com 


---------------------------------------------------------------------
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:     <cocoon-users-unsubscribe@xml.apache.org>
For additional commands, e-mail:   <cocoon-users-help@xml.apache.org>



-- 
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."


Mime
View raw message