forrest-svn mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cross...@apache.org
Subject svn commit: rev 23028 - in forrest/trunk/src/documentation/content/xdocs: . howto howto/v10
Date Sun, 18 Jul 2004 13:27:16 GMT
Author: crossley
Date: Sun Jul 18 06:27:15 2004
New Revision: 23028

Added:
   forrest/trunk/src/documentation/content/xdocs/howto/howto-howto.xml   (contents, props
changed)
Removed:
   forrest/trunk/src/documentation/content/xdocs/howto/v10/
Modified:
   forrest/trunk/src/documentation/content/xdocs/site.xml
Log:
Update the sample "How to write a How-To" to be "DTD How-to V1.2".


Added: forrest/trunk/src/documentation/content/xdocs/howto/howto-howto.xml
==============================================================================
--- (empty file)
+++ forrest/trunk/src/documentation/content/xdocs/howto/howto-howto.xml	Sun Jul 18 06:27:15
2004
@@ -0,0 +1,205 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  Copyright 2002-2004 The Apache Software Foundation
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+-->
+<!DOCTYPE howto PUBLIC "-//APACHE//DTD How-to V1.2//EN" "http://forrest.apache.org/dtd/howto-v12.dtd">
+
+<howto>
+ <header>
+  <title>How to write a How-To</title>
+  <version>0.3</version>
+  <notice>This document is a sample to test the DTD structure and to
+  provide a template for devloping other How-To documents.</notice>
+  <abstract>This How-To describes the steps necessary to write a How-To
+   document. Writing documentation 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>
+Users who are ready to share their knowledge and experiences with the community.
+</p>
+  </audience>
+  
+  <purpose title="Purpose">
+<p>
+These guidelines are based on successful how-to document structures used by other open source
projects with diverse author groups. Following these tried and true guidelines will help to
insure the effectiveness of your work.
+</p>
+  </purpose>
+
+
+  <prerequisites title="Prerequisites">
+<p>
+How-To authors should have:
+</p>
+<ul>
+<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>See the
+<link href="site:howto-v12-dtd">DTD documentation</link> which explains the
+document structure.</note>
+</prerequisites>
+
+  <steps title="Steps">
+<p>
+Here is how to proceed.</p>
+
+  <section>
+    <title>Write the Overview</title>
+<p>
+An overview helps potential readers to determine quickly if a particular How-To matches their
interests or needs. In a few sentences, summarize the main points of your How-To. Make sure
to include any critical definitions which will help readers evaluate the utility of your How-To.
Consider writing the overview last, after you have completed all other sections.
+</p>
+  </section>
+
+  <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 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>
+
+  <section>
+    <title>State the Purpose</title>
+<p>
+State the purpose of your How-To. Explain how the reader will benefit by reading it. Give
your reader an incentive or two to continue. 
+</p>
+  </section>
+
+  <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 Forrest site or the web. Helping your readers to prepare increases the likelihood
that they will continue reading your How-To.
+</p>
+  </section>
+
+  <section>
+    <title>Describe the Steps of your How-To</title>
+<p>
+In a precise, step-by-step approach, walk your reader through the process. Make sure your
reader can reproduce your intended result by following your exact steps. Make the learning
process efficient by supplying sample code snippets or configuration details as necessary.
+</p>
+  </section>
+
+  <section>
+    <title>Extend the Learning</title>
+<p>
+Provide your reader with a few real-world examples of how the techniques or capabilities
gained from your How-To could be applied. Reward the reader for successfully completing the
How-To with a few ideas about how it will pay off.
+</p>
+  </section>
+
+
+  <section>
+    <title>Summarize the Entire Process</title>
+<p>
+In a few sentences, remind the reader what they have just learned. This helps to reinforce
the main points of your How-To.  
+</p>
+  </section>
+
+
+  <section>
+    <title>Additional Tips or FAQs</title>
+<p>
+In some cases, step-by-step instructions simply aren't enough. Use this section to pass on
any other tips or frequently asked questions. Anticipating the needs of your readers will
increase the overall success of your writing effort.
+</p>
+  </section>
+
+  <section>
+    <title>References</title>
+<p>
+Remember to acknowledge any third-party resources or individuals who contributed to the development
of your How-To. Consider providing links for those motivated readers who want to learn more.
+</p>
+  </section>
+  
+  <section>
+    <title>Submit via the project issue tracker</title>
+<p>
+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>Get some feedback</title>
+<p>
+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>
+    
+
+  </steps>
+
+  <extension title="Extension">
+<p>
+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>
+
+  <faqs title="Frequently Asked Questions">
+  
+  <faq>
+   <question>
+    What is the difference between a How-To and a tutorial?
+   </question>
+   <answer>
+    <p>
+    The goal of a How-To is to help the reader to accomplish a specific task with clear and
consise instructions. While tutorials may contain How-To-like instructions and content, they
also include additional background and conceptual content to help teach their readers higher
order concepts along the way. How-Tos are concerned about filling an immediate, short-term
need. Tutorials often provide long-term knowledge which can be applied across a range of needs.
+    </p>
+   </answer>
+  </faq>
+
+  <faq>
+   <question>
+    What spelling convention should I follow?
+   </question>
+   <answer>
+    <p>
+     Use whatever spelling convention (American, British, etc.) that is most intuitive to
you.
+    </p>
+   </answer>
+  </faq>
+  </faqs>
+  
+  <tips title="Tips">
+  
+  <section>
+    <title>How-To dtd</title>
+<p>
+The document structure is likely to change soon. Please note that this HOWTO page is likely
to change as well.
+</p>
+  </section>
+  
+  </tips>
+
+  <references title="References">
+<p>
+This is not the first, nor will it be the last, How-To on writing How-Tos. For other ideas
and opinions on the matter, check out the following sources.
+</p>
+  <ul>
+<li>
+Joel D. Canfield's <link href="http://www.evolt.org/article/How_To_Write_A_How_To/9741/18250/index.html">How
to Write a How-To</link> on evolt.org.
+</li>
+<li>
+The Linux Documentation Project's <link href="http://www.tldp.org/HOWTO/HOWTO-INDEX/index.html">HOWTO</link>
index page provides many excellent How-To documents to inspire your efforts.
+</li>
+  </ul>
+  
+  </references>
+  
+</howto>

Modified: forrest/trunk/src/documentation/content/xdocs/site.xml
==============================================================================
--- forrest/trunk/src/documentation/content/xdocs/site.xml	(original)
+++ forrest/trunk/src/documentation/content/xdocs/site.xml	Sun Jul 18 06:27:15 2004
@@ -99,7 +99,7 @@
 
   <howto label="How-To" href="howto/" tab="howto">
     <overview label="Overview" href="index.html"/>
-    <write-howto label="Write a How-to" href="v10/howto-v10.html"/>
+    <write-howto label="Write a How-to" href="howto-howto.html"/>
   </howto>
 
 <!--
@@ -107,7 +107,7 @@
     <index label="About" href="index.html"/>
     <howto-samples label="How-To Samples" href="howto/" tab="howto">
       <overview label="Overview" href="index.html"/>
-      <single-page label="Single Page" href="v10/howto-v10.html"/>
+      <single-page label="Single Page" href="howto-howto.html"/>
       <multi-page label="Multi-Page" href="multi/">
         <intro label="Intro" href="howto-multi.html"/>
         <step1 label="Step 1" href="step1.html"/>
@@ -117,7 +117,7 @@
       <with-images label="With Images" href="bugzilla-patch/howto-bugzilla-patch.html"/>
     </howto-samples>
     <howto-developers label="Developers" href="howto/" tab="howto">
-      <write-howto label="Write a How-to" href="v10/howto-v10.html"/>
+      <write-howto label="Write a How-to" href="howto-howto.html"/>
     </howto-developers>
     <howto-committers label="Committers" href="howto/" tab="howto">
       <cvs-ssh label="CVS through SSH" href="cvs-ssh/howto-cvs-ssh.html"/>

Mime
View raw message