cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Diana Shannon <>
Subject [input needed] --- documentation questionnaire ---
Date Fri, 19 Apr 2002 20:05:19 GMT
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.

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 

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

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:
For additional commands, email:

View raw message