cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andrew C. Oliver" <acoli...@apache.org>
Subject Re: [input needed] --- documentation questionnaire ---
Date Sun, 21 Apr 2002 13:13:44 GMT
Diana Shannon wrote:

>> ---------
>> 1. Assessing needs
>
>
> Here's what my document to-do list would look like. I realize some of 
> this content already exists (within examples, cocoon.xconf, 
> sitemap.xmap, the APIs, etc.). The proposed documentation structure 
> would help to make this content more accessible.
>
> Tutorial
> - A real newbie tutorial, one that does *not* require configuring a 
> database.

Most applications that would utilize Cocoon would utilize a database at 
some point.  I would suggest a preconfigured HSQL database (which 
already exists for some of the examples) would be sufficient.  But if 
its on the level of "here is the site map, here is xml, here is an xsl,  
here is a serializer put them together" then I agree.

>
> How-tos
> - How to configure C2 (prior to build) 

include how to install/pick out optional components.

>
> - How to configure C2 (for development) 

include how to code inside of
                1. netbeans/forte (same monster, two faces)
                2. jbuilder
                3. idea
                4. ?

>
> - How to configure C2 (for deployment)
> - How to host C2 (for ISPs) 

include how to virtually host to remove /cocoon context.

>
> - How to troubleshoot within the C2 development environment 

Explain the stack traces and how the error is usually exactly 1/2 of the 
page down.

>
> - How to test your C2 webapp 

Explain the use of apachebench (ab) which comes with httpd for basic 
load testing.  wget for single user test.  Others?

>
> - How to use C2 documentation (road map for different learners) 

Do this last.

<snip content="good stuff"/>

>
I'll be working on an example webapp with a live example.  

>
>> ---------
>> 2. Accessibility
>> Considering the documenation that already exists, how can we make it 
>> more readily accessible? In other words, how can we reduce the amount 
>> of time and effort required to locate and apply the necessary 
>> information? How do we avoid information fragmentation? Please 
>> add/delete/edit as you see fit.
>
In the webapp example I'll be working on I hope to provide a "getting 
started" guide similar to the one I wrote for Lucene 
http://jakarta.apache.org/lucene/docs/gettingstarted.html though the 
example will be more elaborate.  I'll include references to various 
components of the rest of the documentation.

> <snip content="good stuff"/>
>
>> -----------
>> 3. What do you consider to be reasonable short- and long-term goals 
>> of this effort? What should be the priorities?
>
>
> Short-term
> 1. Improve existing docs. High priority. 

+1

>
> 2. Add docs for beginner and intermediate users. High priority. 

+1

>
> 3. Form documentation team. High priority.

elaborate what you mean by this...

>
>> 4. How can we make the best use of available resources? How can we 
>> leverage untapped resources within the Cocoon community?
>
>
> 1. Post *short* documentation survey to user list. Ask what they need, 
> specifically.
> 2. Recruit "reviewers" (of different levels of abilities and 
> experience with C2) from the cocoon-user list to provide feedback on 
> drafts. 

I volunteer.

>
> 3.  Solicit "how-to" submissions from Cocoon community.

I'll be providing one.  I think we should have a www.linuxdoc.org style 
effort of "how-tos"

>
>> -----------
>> 5. How do we focus our efforts to complement -- not compete with -- 
>> third-party book and training efforts? In other words, what strategic 
>> niche can online documentation fill? For example, online 
>> documentation can be less formal, more current, less linear (with 
>> multiple ways to navigate), and more responsive (meeting needs as 
>> they arise) than traditional print documentation. How might 
>> third-party authors and trainers contribute to the Cocoon's 
>> documentation without diminishing the results of their own efforts?
>
>
> Focus efforts on incremental development of useful, updated content 
> that users need *now*. If this effort results in enough content -- in 
> the future -- for a comprehensive manual, great. However, at the 
> present time, IMHO we should leave the writing of manuals to 
> third-parties.

I don't think we should consider that we might mess up someones book 
deal if we document things too well.  That is not only inlikely but 
seems to me to be the type of thinking of corrupt politicians rather 
than software folks. ;-)

>
>> -----------
>> 6. What documentation projects/examples do you admire? Any URLs or 
>> specific references will be greatly appreciated.
>
>
> 1. Interesting suggestion to me off-list was a wiki site.

wiki is not adequate documentation.  I do think a wiki might be useful, 
but you do want something more....organized... for *real* documentation. 
 A wiki could definately encourage user participation.  Once I get my 
server rebuilt, if someone will help with it and agree to help me set it 
up and maintian it, I may be willing to help here..  I'll need to give 
it some thought.

>
>> -----------
>> 8. How can we make it easier/more inviting for people to participate 
>> in the document development process? What kinds of architectural 
>> mechanisms can we implement to support document 
>> development/refinement, given the current hosting environment of 
>> Cocoon's web site?
>
>
> 1. Is bugzilla the optimal way/place to gather user feedback? Is it 
> possible to design a more friendly front-end or a separate form 
> altogether? 

I would suggest that thats proably more effort than you think, and that 
the mail lists are sufficient.  Bugzilla is probably insufficient.  A 
wiki would probably help.

>
> 2. Interesting suggestion to me off-list was a separate cocoon-doc 
> list for discussion of doc needs, evaluations of drafts, etc..

NO!!!!!!!!!!!!!!! -100000000  That discourages participation and makes 
it easier for developers to hide themselves in the tower and not be 
bothered with documentation.  This is the WRONG kind of thinking. 
 Documentation is everyone's concern.

-Andy

>
> Diana Shannon
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
>




---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org


Mime
View raw message