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