svn commit: rev 23016 - forrest/trunk/src/documentation/content/xdocs/howto/v10

[cr...@apache.org]

Author: crossley
Date: Sun Jul 18 01:09:42 2004
New Revision: 23016

Modified:
   forrest/trunk/src/documentation/content/xdocs/howto/v10/howto-v10.xml
Log:
Content was too Cocoon-specific.
Contribute first, then review.
Encourage feedback on the mailing lists rather than privately.


Modified: forrest/trunk/src/documentation/content/xdocs/howto/v10/howto-v10.xml
==============================================================================
--- forrest/trunk/src/documentation/content/xdocs/howto/v10/howto-v10.xml	(original)
+++ forrest/trunk/src/documentation/content/xdocs/howto/v10/howto-v10.xml	Sun Jul 18 01:09:42 2004
@@ -18,17 +18,18 @@
 
 <howto>
  <header>
-  <title>How to Author a How-To</title>
-  <version>0.2</version>
-  <notice>This document is a sample to test the new howto-v11.dtd</notice>
-  <abstract>This How-To describes the steps necessary to write a How-To for Cocoon. The Cocoon documentation project needs your help. Writing a Cocoon How-To is a valuable way to give back to the community.</abstract>
-  <last-modified-content-date date="2002-05-19"/>
+  <title>How to write a How-To</title>
+  <version>0.3</version>
+  <notice>This document is a sample to test the DTD structure</notice>
+  <abstract>This How-To describes the steps necessary to write a How-To
+   document. Writing a How-To is a valuable way to give back to the community.
+  </abstract>
+  <last-modified-content-date date="2004-07-18"/>
  </header>
 
-
   <audience title="Intended Audience">
 <p>
-Cocoon users who are ready to share their knowledge and experiences with the larger Cocoon community.
+Users who are ready to share their knowledge and experiences with the community.
 </p>
   </audience>
   
@@ -44,16 +45,19 @@
 How-To authors should have:
 </p>
 <ul>
-<li>A unique How-To topic, related to using Cocoon, which fulfills a specific need. Check out existing How-Tos to find a niche for your work. Consider posting your idea for the How-To to cocoon-user list, to make sure another author's draft is not already in process.</li>
-<li>A sufficient ability in English to write the FAQ. If you need a little extra help with language, consider partnering with another user with more advanced English writing skills.</li>
-<li>Currently, the Cocoon documentation project is still working out the exact details for a How-To dtd and template. For now, just edit the most recent version of any existing How-To, filling in your own content as necessary. Make sure you use most recent version of document dtd to validate your How-To before submitting. You will find it in <code>src/documentation/xdocs/dtd</code> in your cocoon distribution.</li>
+<li>A unique How-To topic, related to using Forrest, which fulfills a specific need. Check out existing How-Tos to find a niche for your work. Consider posting your idea for the How-To to user mailing list, to make sure another author's draft is not already in process.</li>
+<li>A sufficient ability in English to write the FAQ. However, we would rather that you just make a start, as the community can help to fine-tune the document.</li>
+<li>Currently, the Forrest project is still working out the exact details for a How-To dtd and template. For now, just edit the most recent version of any existing How-To, filling in your own content as necessary. Make sure you run
+'<code>forrest validate-xdocs</code>' before contributing your document.</li>
 </ul>
-<note>Within Forrest, the dtd is located in <code>src/resources/schema/dtd</code>.</note>
+<note>See the
+<link href="site:howto-v12-dtd">DTD documentation</link> which explains the
+document structure.</note>
 </prerequisites>
 
   <steps title="Steps">
 <p>
-Here's how to proceed.</p>
+Here is how to proceed.</p>
 
   <section>
     <title>Write the Overview</title>
@@ -65,7 +69,7 @@
   <section>
     <title>Describe your Intended Audience</title>
 <p>
-If your How-To is targetted at a specific audience, describe it here. For example, potential readers will have different levels of skill using Cocoon. They will also bring different areas of expertise and backgrounds to their How-To learning experience. When you clarify your target audience up front, you will save all other readers time and confusion. 
+If your How-To is targetted at a specific audience, describe it here. For example, potential readers will have different levels of skill using Forrest. They will also bring different areas of expertise and backgrounds to their How-To learning experience. When you clarify your target audience up front, you will save all other readers time and confusion. 
 </p> 
   </section>
 
@@ -79,7 +83,7 @@
   <section>
     <title>List any Prerequsites</title>
 <p>
-Inform your reader about any required knowledge, configuration, or resources they may need before stepping through your How-To. Assist them in this preparation by linking to other useful resources on the Cocoon site or the web. Helping your readers to prepare increases the likelihood that they will continue reading your How-To.
+Inform your reader about any required knowledge, configuration, or resources they may need before stepping through your How-To. Assist them in this preparation by linking to other useful resources on the Forrest site or the web. Helping your readers to prepare increases the likelihood that they will continue reading your How-To.
 </p>
   </section>
 
@@ -121,17 +125,19 @@
   </section>
   
   <section>
-    <title>Get some feedback</title>
+    <title>Submit via the project issue tracker</title>
 <p>
-Ask a few other Cocoon users to proofread your How-To. Or, post a text version of it to the cocoon-user list, and ask for comments.
+Create an attachment for your How-To document, and submit it via the project
+<link href="site:bugs">issue tracker</link>.
 </p> 
   </section>
   
   <section>
-    <title>Submit via Bugzilla</title>
+    <title>Get some feedback</title>
 <p>
-Create an attachment for your How-To document, and submit it via Bugzilla. 
-<!-- link to How-To Bugzilla here -->
+When the committers have added your document then it will be available for
+everyone to to build upon and enhance. Feedback will happen via the
+<link href="site:mail-lists">mailing lists</link>.
 </p> 
   </section>
     
@@ -140,7 +146,7 @@
 
   <extension title="Extension">
 <p>
-Cocoon solutions can be extended to cover many different problem domains. A nearly unlimited number of potential How-To topics, from simple to complex, are available right now, limited only by your imagination. 
+Solutions can be extended to cover many different problem domains. A nearly unlimited number of potential How-To topics, from simple to complex, are available right now, limited only by your imagination. 
 </p>
   </extension>
 
@@ -174,7 +180,7 @@
   <section>
     <title>How-To dtd</title>
 <p>
-The document structure of Cocoon's How-To page is likely to change soon. Please note that this HOWTO page is likely to change as well.
+The document structure is likely to change soon. Please note that this HOWTO page is likely to change as well.
 </p>
   </section>