Purpose The goal of this questionnaire is to gather feedback and advice on how to improve the Cocoon project's documentation. Its structure is intended to help frame -- but not necessarily limit -- the discussion. Your input will inform and direct the drafting of an action plan to address documentation needs.
Issue Documentation exists to meet the anticipated needs of an intended audience. Common online document types include: in-depth as well as quick reference guides; conceptual, "big-picture" overviews; how-tos; tutorials; and manuals. These document types address different needs for different audiences. The issue at hand: how can we improve Cocoon's documentation to meet the needs of its audience more successfully? Or, to put it another way, how do we restore the implication of "fine" to the expression "RTFM"? --------- 1. Assessing needs Cocoon has been referred to as "glue technology" on this list. Cocoon's audience includes a varied group of people, each with different levels of expertise, expectations, and needs. Very generally speaking, this audience reads existing documents in order to evaluate, learn about, develop with, and contribute to Cocoon. Here is a *rough* first attempt to match needs to documents. Please revise it as you find appropriate. I intentionally kept it general to conserve space. However, please provide enough detail in your response so that it's clear what needs to be added to the documentation to-do list. Note the meaning of following symbols: + existing documentation meets this need - existing documentation partially meets this need o no documentation currently meets this need Evaluating C2 (new users, managers, administrators, press) - conceptual, big-picture pieces - news - features o requirements o (links to) third party reviews, press o success stories o comparison to other technologies/approaches o development roadmap Learning to use C2 (introductory/intermediate/advanced users) - conceptual, big-picture pieces - FAQs - tutorials (multiple levels) - guides to additional components o manual o learner's roadmaps o glossary of terms o (links to) external resources/aids Developing with C2 (introductory/intermediate/advanced users) + API reference + Bug Database - FAQs - how-tos (download, build, install, configure, test, debug, extend, etc.) - sitemap components reference guide - configuration reference guide - samples/snippets/cookbook - hosting information o best practices o (links to) external resources/aids Contributing to C2 (community donations of code, documentation, resources, etc.) + Bug Database + Code Respository + to do (code) + instructions (for developers) o how-tos o FAQs o instructions (for all other types of contributions) o source code style conventions --------- 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. Problem: Site navigation does not reflect common use cases. Solution: Revise navigation hierarchy. Add pages with suggested roadmaps, based on needs. Problem: There is inconsistent structure within document types. For example, some user documents, classified as "concept" pieces, contain a lot of configuration and how-to detail. Solution: Edit existing documents. Break them up into separate documents (and types) if necessary. Design templates for different document types. Design author's guidelines. Problem: Content overlap among documents. Solution: Edit existing documents. Problem: Some documents are overly long. Solution: Break up content into multiple pages. Problem: FAQs page is overly dense. Solution: Group FAQs by use/need. Migrate FAQ topics to different document contexts. ----------- 3. What do you consider to be reasonable short- and long-term goals of this effort? What should be the priorities? Example: Improve and expand newbie and intermediate developer/learner documentation. High priority. ----------- 4. How can we make the best use of available resources? How can we leverage untapped resources within the Cocoon community? Example: Recruit "reviewers" from the cocoon-user list to provide feedback on drafts. Example: Solicit "how-to" submissions from Cocoon community. (A search of "how-to" at zope.org yielded 578 different community submissions!) ----------- 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? ----------- 6. What documentation projects/examples do you admire? Any URLs or specific references will be greatly appreciated. Example: Check out http://www.zope.org/DocProjects/ ----------- 7. What's currently difficult about contributing/authoring documentation for C2 right now? How can we improve that process? Example: Provide authoring templates and guidlines. Provide editorial/writing style guides. Example: Have authors submit outlines of proposed documents for comments/review prior to writing them. Example: Gather feedback on works in process from the intended audience. ----------- 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? ----------- 9. How might subscribers to this list contribute to this effort? ----------- 10. What have I missed? Thanks in advance for your input and time. Diana Shannon --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
