cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <terrac...@mac.com>
Subject Re: [input needed] --- documentation questionnaire ---
Date Sun, 21 Apr 2002 11:31:49 GMT
> ---------
> 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.

How-tos
- How to configure C2 (prior to build)
- How to configure C2 (for development)
- How to configure C2 (for deployment)
- How to host C2 (for ISPs)
- How to troubleshoot within the C2 development environment
- How to test your C2 webapp
- How to use C2 documentation (road map for different learners)
- How to experiment with new C2 developments (work with cvs-head, 
scratchpad)
- How to use built-in actions (different how-tos)
- How to design your own action/generator/transformer, etc. (multiple 
how-tos with concrete example)
- How to implement security/authorization (multiple levels, approaches)
- How to validate form input, multiple approaches (I know this is 
evolving, but some users feel you can't validate at all, server-side, 
using C2)
- How to configure databases (multiple how-tos for different databases)
- How to integrate C2 webapp into hosting environment (with other 
webapps)
- How to use the command line version of Cocoon
- Suggestions for integrating C2 into development environment (IDEs, 
filesystem structure, cvs updates)
- Suggestions for integrating C2 into client/customer environment 
(third-party tools, slash-edit, etc.)

Reference Guides
- Guide for all built-in pipeline components with descriptions of 
parameters (I know this exists, but it's incomplete. I know some of this 
info is in the API, but it's inefficient for users to find.)
- Guide for all built-in logicsheet tags (just tags and their meaning, 
not introductory material)

Mini-guides
- Sitemap  (consolidate and enhance lots of existing info into an 
integrated set of documents)
- More guides (like Sunshine) for new components when appropriate
- Forms
- I18N issues

Examples/Cookbook
- Individual pages for *all* current examples. I know, *some* examples 
include a background page, but most others only demonstrate the example. 
Users need a bit more detail than a one- or two-sentence description.

Best Practices
- Pipeline design
- XSP to generator conversion
- XSLT within C2

Informational Pages
- How to contribute to Cocoon documentation effort
- Tips on how to write documentation (multiple pages, based on document 
type)
- Tips on how to review documentation

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

Many examples in the sitemap are great. They just need a bit more 
documentation (added above). Current users seem to overlook examples or 
fail to associate them with the problem they are trying to solve.

Revise site navigation menu (separate email topic?). Eliminate 
distinction between user and developer guides. I think this separation 
is somewhat arbitrary and discourages users.

Restructure some existing documentation. Revise documents to reveal 
intended audience, level of use, related information/links, etc. Apply 
global English editing techniques. Add more examples within documents. 
Add more detail within explanations to reinforce new/difficult concepts.


> -----------
> 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.
2. Add docs for beginner and intermediate users. High priority.
3. Form documentation team. High priority.

> 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.
3.  Solicit "how-to" submissions from Cocoon community.

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

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

> -----------
> 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?
2. Interesting suggestion to me off-list was a separate cocoon-doc list 
for discussion of doc needs, evaluations of drafts, etc..

Diana Shannon


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


Mime
View raw message