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: [EMAIL PROTECTED]
> For additional commands, email: [EMAIL PROTECTED]
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
