cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject cvs commit: xml-cocoon2/src/documentation/xdocs/plan issues-doc.xml
Date Thu, 04 Jul 2002 01:32:19 GMT
shannon     2002/07/03 18:32:19

  Added:       src/documentation/xdocs/plan issues-doc.xml
  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">
     <person name="David Crossley" email=""/>
     <person name="Diana Shannon" email=""/>
   <s1 title="Issues">
  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="">Forrest</link> Project.
  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.
  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.
  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.
    <s1 title="Revisions required">
    <s2 title="XSP Internals">
      <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.
   <s1 title="Fix any placeholder documents">
     These pages have a shell, but no content yet. They currently have the
     embarrassing &quot;Under Construction&quot; type of notice.
     <li>Index pages for &quot;Developing&quot; and &quot;Userdocs&quot;</li>

In case of troubles, e-mail:
To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message