shannon 2002/07/03 18:36:13
Modified: src/documentation/xdocs/plan doc.xml
Log:
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 @@
<document>
<header>
- <title>Documentation Revisions and Additions</title>
+ <title>About the Cocoon Documentation Effort</title>
<subtitle>Overview</subtitle>
<authors>
<person name="David Crossley" email="[EMAIL PROTECTED]"/>
+ <person name="Diana Shannon" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<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>
-
- <p>Please also see the <link href="todo-doc.html">Documentation To Do
- List</link> and the <link href="changes-doc.html">Documentation History of
- 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="http://xml.apache.org/forrest/";>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.
</p>
- </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">
+<p>
+Find out what documentation efforts are already in process among other users and
committers. First and foremost, join the Cocoon <link
href="mailto:[EMAIL PROTECTED]";>docs list</link>.
+</p>
</s2>
- <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>
</s2>
-
- </s1>
-
- <s1 title="Fix any placeholder documents">
-
+
+ <s2 title="Other Information">
<p>
- These pages have a shell, but no content yet. They currently have the
- embarrassing "Under Construction" 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 list.
</p>
-
- <ul>
- <li>Index pages for "Developing" and "Userdocs"</li>
- <li>userdocs/actions/actions.xml</li>
- </ul>
- </s1>
-
- <s1 title="Additional documents required">
-
- <ul>
- <li></li>
- </ul>
+ </s2>
</s1>
- <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>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
