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 Forrest Project.

The Cocoon Wiki has listings of some new documentation that is needed. See DocsWishlist and CocoonDocsDrafts.

• 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 configuration changes.
• 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.

• This document (userdocs/xsp/xsp-internals.xml) had stacks of broken links to old Javadocs. Perhaps this indicates that the whole document needs revision.

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"
• userdocs/actions/actions.xml