Certain issues need to be addressed for all current and future documentation.
Many of these issues are being addressed and discussed on the
cocoon-docs mailing list.
Documentation infrastructure issues are also addressed on the Apache
The Cocoon Wiki has listings of some new documentation that is needed. See
Many pages use source elements to list code or configuration information.
Wide pre-formatted text lines do not word-wrap in HTML output and so the
user would need to painfully scroll left-and-right to read the page. While Forrest
transition will address this issue, many users would appreciate any
efforts to fix this problem asap. Therefore, all new doc contributions should be screened for this problem. All existing docs, when edited, should have this problem fixed as well.
All documentation needs to be continually revised. It cannot be written
and then never updated. It needs to keep in step with the code and
Cocoon has various tools to assist with monitoring broken hyperlinks.
There is a separate document to explain the
linkstatus and show how you can help to
ensure robustness of the documentation set and the website.
Many docs need examples to illustrate conceptual ideas. The examples contained
in some docs are ok, but many docs need to be supplemented with "real-world" examples
that address the architectural problems webapp developers face. The best docs start
with a simple example and then continue with a more complex example.
Many docs need summaries at the end of the text to reinforce some of the more complicated points made earlier in the document text. The use of reinforcing, but slighly different, language may help users fully grasp the main points.
Many docs need comparison tables, to outline the pros and cons of different components or problem solving strategies.
Now that the FAQ section is expanding, we need to start incorporating some of the FAQ content back into the core docs.
More docs need "motivational" content which explains how a particular component or
approach can be applied to the user's benefit.
Fix any placeholder documents
This document (userdocs/xsp/xsp-internals.xml) had stacks of broken
links to old Javadocs. Perhaps this indicates that the whole document
These pages have a shell, but no content yet. They currently have the
embarrassing "Under Construction" type of notice.
Index pages for "Developing" and "Userdocs"