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 doc.xml
Date Thu, 04 Jul 2002 01:36:13 GMT
shannon     2002/07/03 18:36:13

  Modified:    src/documentation/xdocs/plan doc.xml
  Revised to advertise new documentation
  effort and all its new resources:
  docs-list, guidelines, and Forrest.
  Added pointers to all documentation
  guidelines as well as other doc
  planning docs.
  Revision  Changes    Path
  1.5       +25 -73    xml-cocoon2/src/documentation/xdocs/plan/doc.xml
  Index: doc.xml
  RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/plan/doc.xml,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- doc.xml	13 May 2002 16:24:17 -0000	1.4
  +++ doc.xml	4 Jul 2002 01:36:13 -0000	1.5
  @@ -3,99 +3,51 @@
  -  <title>Documentation Revisions and Additions</title>
  +  <title>About the Cocoon Documentation Effort</title>
      <person name="David Crossley" email=""/>
  +   <person name="Diana Shannon" email=""/>
    <s1 title="Overview">
  -  <p>Of course, the Cocoon documentation is always undergoing evolution.
  -   These notes remind us of some things that have been discussed and not
  -   yet implemented.
  -  </p>
  -  <p>The following sections list some documents that need revision and some
  -   required additional documents. At the bottom is a list of general issues.
  +  <p>
  +There is a concerted effort underway at this time to improve Cocoon's documentation. This
effort is based on the belief that open source documents can be as first-rate as the software
on which they are based. However, such an endeavor is entirely dependent upon vital and timely
forms of contributions from developers and users alike. Make no mistake about it; everyone
is needed and invited to participate in this effort!
  -  <p>Please also see the <link href="todo-doc.html">Documentation To Do
  -   List</link> and the <link href="changes-doc.html">Documentation History
  -   Changes</link>.
  +  <p>
  +While we have a lot to do, there are evolving structures in place to facilitate and enhance
your efforts. We have numerous guidelines for authoring documents, a document-specific email
list, and a complementary documentation architectural project at <link href="">Forrest</link>.
If you choose to become involved, you will discover many like-minded developers and users
who care about Cocoon documentation and will support your effort. Here are a few ideas to
help you get started. 
  - </s1>
  - <s1 title="Revisions required">
  -  <s2 title="Frequently Asked Questions">
  -   <ul>
  -    <li>Needs re-structure or we will have the same un-wieldy monster FAQ as
  -      for Cocoon 1.
  -    </li>
  -   </ul>
  +  <s2 title="Cocoon Docs List">
  +Find out what documentation efforts are already in process among other users and committers.
First and foremost, join the Cocoon <link href="">docs
  -  <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 title="Forms of Document Contributions">
  +  <p>
  +Check out Cocoon's How-To guidelines to learn about the variety of ways to contribute or
improve Cocoon documents.
  +  </p>
  +	<ul>
  +<li><link href="../howto/howto-author-faq.html">How to Author an FAQ</link></li>
  +<li><link href="../howto/howto-author-howto.html">How to Author a How-To</link></li>
  +<li><link href="../howto/howto-author-snippet.html">How to Author a Code Snippet</link></li>
  +<li><link href="../howto/howto-author-core-docs.html">How to Author Core Documentation</link></li>
  +	</ul>
  - </s1>
  - <s1 title="Fix any placeholder documents">
  +    <s2 title="Other Information">
  -   These pages have a shell, but no content yet. They currently have the
  -   embarrassing &quot;Under Construction&quot; type of notice.
  +If you're interested in reviewing recent documentation additions or substantive modifications,
see the documentation <link href="changes-doc.html"> History of Changes</link>.
You may also want to check out the documentation-specific <link href="todo-doc.html">To-Do
List</link>. You can also take an advance look at a proposed <link href="proposed-toc.html">table
of contents</link> for a revised Cocoon guide. You may also be interested in reviewing
some <link href="issues-doc.html">general and specific issues</link> related to
Cocoon documentation. Your comments and feedback on any of the above are welcome on the cocoon-docs
  -  <ul>
  -   <li>Index pages for &quot;Developing&quot; and &quot;Userdocs&quot;</li>
  -   <li>userdocs/actions/actions.xml</li>
  -  </ul>
  - </s1>
  - <s1 title="Additional documents required">
  -  <ul>
  -   <li></li>
  -  </ul>
  +  </s2>
  - <s1 title="General Issues">
  -  <p>Certain issues need to be addressed for all current and future
  -   documentation.
  -  </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.
  -   </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 internal or external links. Please
  -    see the README file at
  -    <link href="linkalarm-readme.txt">linkalarm-readme.txt</link>
  -    and help to attend to any issues.
  -   </li>
  -  </ul>
  - </s1>

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

View raw message