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="[EMAIL PROTECTED]"/>
<person name="Diana Shannon" email="[EMAIL PROTECTED]"/>
</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: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
