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: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
|