You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by sh...@apache.org on 2002/07/04 03:32:19 UTC
cvs commit: xml-cocoon2/src/documentation/xdocs/plan issues-doc.xml
shannon 2002/07/03 18:32:19
Added: src/documentation/xdocs/plan issues-doc.xml
Log:
Pulled content for this
document out of main doc
overview: doc.xml. Supplemented
issues with my own as well
as feedback gathered from
cocoon users.
Revision Changes Path
1.1 xml-cocoon2/src/documentation/xdocs/plan/issues-doc.xml
Index: issues-doc.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
<document>
<header>
<title>Issues</title>
<subtitle>Overview</subtitle>
<authors>
<person name="David Crossley" email="crossley@apache.org"/>
<person name="Diana Shannon" email="shannon@apache.org"/>
</authors>
</header>
<body>
<s1 title="Issues">
<p>
Certain issues need to be addressed for all current and future
documentation. Please note that many of these issues are being addressed or discussed on the Apache <link href="http://xml.apache.org/forrest/">Forrest</link> Project.
</p>
<ul>
<li>
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.
</li>
<li>
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.
</li>
<li>
The excellent LinkAlarm service is used after each major public release
of Cocoon to help discover any broken external links. (Internal links
are evaluated during the docs build.) Please see the README file at <link href="linkalarm-readme.txt">linkalarm-readme.txt</link>
and help to attend to any issues. However, the site is updated more
frequently now, so the cost of using LinkAlarm may not be wise. We need to take advantage of the capabilities of Cocoon's LinkStatus Generator. Perhaps this can be incorporated into a custom build target for docs.
</li>
<li>
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.
</li>
<li>
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.
</li>
<li>
Many docs need comparison tables, to outline the pros and cons of different components or problem solving strategies.
</li>
<li>
Now that the FAQ section is expanding, we need to start incorporating some of the FAQ content back into the core docs.
</li>
<li>
More docs need "motivational" content which explains how a particular component or
approach can be applied to the user's benefit.
</li>
</ul>
</s1>
<s1 title="Revisions required">
<s2 title="XSP Internals">
<ul>
<li>This document (userdocs/xsp/xsp-internals.xml) had stacks of broken
links to old Javadocs. Perhaps this indicates that the whole document
needs revision.
</li>
</ul>
</s2>
</s1>
<s1 title="Fix any placeholder documents">
<p>
These pages have a shell, but no content yet. They currently have the
embarrassing "Under Construction" type of notice.
</p>
<ul>
<li>Index pages for "Developing" and "Userdocs"</li>
<li>userdocs/actions/actions.xml</li>
</ul>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: webmaster@xml.apache.org
To unsubscribe, e-mail: cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org