Google Git
Sign in
apache / forrest / refs/tags/forrest_08_release_site / . / howto-howto.html
blob: aa562d99fc57fc5659ef2ee74eab66d35a88ac6e [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta content="Apache Forrest" name="Generator">
<meta name="Forrest-version" content="0.8-dev">
<meta name="Forrest-skin-name" content="pelt">
<title>How to write a How-To</title>
<link type="text/css" href="skin/basic.css" rel="stylesheet">
<link media="screen" type="text/css" href="skin/screen.css" rel="stylesheet">
<link media="print" type="text/css" href="skin/print.css" rel="stylesheet">
<link type="text/css" href="skin/profile.css" rel="stylesheet">
<script src="skin/getBlank.js" language="javascript" type="text/javascript"></script><script src="skin/getMenu.js" language="javascript" type="text/javascript"></script><script src="skin/fontsize.js" language="javascript" type="text/javascript"></script>
<link rel="shortcut icon" href="favicon.ico">
</head>
<body onload="init()">
<script type="text/javascript">ndeSetTextSize();</script>
<div id="top">
<!--+
|breadtrail
+-->
<div class="breadtrail">
<a href="http://www.apache.org/">apache</a> &gt; <a href="http://forrest.apache.org/">forrest</a><script src="skin/breadcrumbs.js" language="JavaScript" type="text/javascript"></script>
</div>
<!--+
|header
+-->
<div class="header">
<!--+
|start group logo
+-->
<div class="grouplogo">
<a href="http://www.apache.org/"><img class="logoImage" alt="Apache" src="images/apache-forrest.png" title="The Apache Software Foundation"></a>
</div>
<!--+
|end group logo
+-->
<!--+
|start Project Logo
+-->
<div class="projectlogo">
<a href="http://forrest.apache.org/"><img class="logoImage" alt="Forrest" src="images/project-logo.gif" title="Apache Forrest"></a>
</div>
<!--+
|end Project Logo
+-->
<!--+
|start Search
+-->
<div class="searchbox">
<form action="http://www.google.com/search" method="get" class="roundtopsmall">
<input value="forrest.apache.org" name="sitesearch" type="hidden"><input onFocus="getBlank (this, 'Search the site with google');" size="25" name="q" id="query" type="text" value="Search the site with google">&nbsp;
<input name="Search" value="Search" type="submit">
</form>
</div>
<!--+
|end search
+-->
<!--+
|start Tabs
+-->
<ul id="tabs">
<li>
<a class="unselected" href="index.html">Welcome</a>
</li>
<li class="current">
<a class="selected" href="contrib.html">Developers</a>
</li>
<li>
<a class="unselected" href="versions/index.html">Versioned Docs</a>
</li>
<li>
<a class="unselected" href="pluginDocs/index.html">Plugins</a>
</li>
<li>
<a class="unselected" href="tools/index.html">Tools</a>
</li>
</ul>
<!--+
|end Tabs
+-->
</div>
</div>
<div id="main">
<div id="publishedStrip">
<!--+
|start Subtabs
+-->
<div id="level2tabs"></div>
<!--+
|end Endtabs
+-->
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<!--+
|breadtrail
+-->
<div class="breadtrail">
&nbsp;
</div>
<!--+
|start Menu, mainarea
+-->
<!--+
|start Menu
+-->
<div id="menu">
<div onclick="SwitchMenu('menu_1.1', 'skin/')" id="menu_1.1Title" class="menutitle">Getting involved</div>
<div id="menu_1.1" class="menuitemgroup">
<div class="menuitem">
<a href="contrib.html" title="Everyone is a developer and has something to contribute">Contributing</a>
</div>
<div class="menuitem">
<a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists and discussion</a>
</div>
<div class="menuitem">
<a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Reporting bugs and issues</a>
</div>
<div class="menuitem">
<a href="forrest-friday.html" title="ForrestFriday monthly get-together">ForrestFriday IRC</a>
</div>
<div class="menuitem">
<a href="events.html" title="List of upcoming related conferences and meetings">Events</a>
</div>
<div onclick="SwitchMenu('menu_1.1.6', 'skin/')" id="menu_1.1.6Title" class="menutitle">Project</div>
<div id="menu_1.1.6" class="menuitemgroup">
<div class="menuitem">
<a href="guidelines.html" title="Open development guidelines to encourage participation">Project guidelines</a>
</div>
<div class="menuitem">
<a href="committed.html" title="Notes about contribution">Being committed</a>
</div>
<div class="menuitem">
<a href="roles.html" title="Tasks to keep the project flowing">Project roles</a>
</div>
</div>
</div>
<div onclick="SwitchMenu('menu_1.2', 'skin/')" id="menu_1.2Title" class="menutitle">Resources and Infrastructure</div>
<div id="menu_1.2" class="menuitemgroup">
<div class="menuitem">
<a href="asf-infrastructure.html" title="Explain the ASF infrastructure">Introduction</a>
</div>
<div class="menuitem">
<a href="mail-lists.html" title="Discussion mail lists are the heart of the project: dev, user, svn">Mail lists</a>
</div>
<div class="menuitem">
<a href="issues.html" title="Issue tracker manages known issues and desired enhancements">Issue management</a>
</div>
<div class="menuitem">
<a href="svn.html" title="Access to the Subversion (SVN) version control system">Version control</a>
</div>
<div class="menuitem">
<a href="http://forrest.zones.apache.org/" title="Demonstrations and testbed at forrest.zones.apache.org">Demonstrations</a>
</div>
<div class="menuitem">
<a href="gump.html">Gump integration</a>
</div>
<div onclick="SwitchMenu('menu_1.2.7', 'skin/')" id="menu_1.2.7Title" class="menutitle">Planning notes</div>
<div id="menu_1.2.7" class="menuitemgroup">
<div class="menuitem">
<a href="plan/index.html">Overview</a>
</div>
<div class="menuitem">
<a href="plan/internal-xhtml.html">Internal XHTML</a>
</div>
</div>
<div class="menuitem">
<a href="todo.html">Todo</a>
</div>
</div>
<div onclick="SwitchMenu('menu_selected_1.3', 'skin/')" id="menu_selected_1.3Title" class="menutitle" style="background-image: url('skin/images/chapter_open.gif');">Best Practices and Procedures</div>
<div id="menu_selected_1.3" class="selectedmenuitemgroup" style="display: block;">
<div class="menuitem">
<a href="howto-dev.html" title="Describes tips and procedures for efficiently developing with Forrest.">Development tips</a>
</div>
<div class="menuitem">
<a href="subversion_bestpractices.html" title="Best practice notes for Subversion">Subversion</a>
</div>
<div class="menuitem">
<a href="documentation_bestpractices.html" title="Best practice notes for documentation">Documentation</a>
</div>
<div class="menupage">
<div class="menupagetitle">Write a How-to</div>
</div>
<div onclick="SwitchMenu('menu_1.3.5', 'skin/')" id="menu_1.3.5Title" class="menutitle">Committer notes</div>
<div id="menu_1.3.5" class="menuitemgroup">
<div class="menuitem">
<a href="zone.html" title="Notes for committers to manage forrest.zones.apache.org">Zone management</a>
</div>
<div class="menuitem">
<a href="procedures/release/How_to_release.html" title="Instructions on preparing and creating a new Forrest release.">How to release</a>
</div>
<div class="menuitem">
<a href="procedures/How_to_publish_docs.html" title="Instructions on publishing the Forrest Website">Publishing Forrest documentation</a>
</div>
</div>
</div>
<div onclick="SwitchMenu('menu_1.4', 'skin/')" id="menu_1.4Title" class="menutitle">Proposals</div>
<div id="menu_1.4" class="menuitemgroup">
<div class="menuitem">
<a href="proposal-asf-forrestbot.html">ASF Forrestbot</a>
</div>
</div>
<div id="credit"></div>
<div id="roundbottom">
<img style="display: none" class="corner" height="15" width="15" alt="" src="skin/images/rc-b-l-15-1body-2menu-3menu.png"></div>
<!--+
|alternative credits
+-->
<div id="credit2">
<a href="http://apachecon.com/2007/EU/"><img border="0" title="ApacheCon Europe 2007" alt="ApacheCon Europe 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-europe-125x125.png" style="width: 125px;height: 125px;"></a><a href="http://people.apache.org/calendar.html#200711"><img border="0" title="ApacheCon US 2007" alt="ApacheCon US 2007 - logo" src="http://apache.org/ads/ApacheCon/2007-usa-125x125.png" style="width: 125px;height: 125px;"></a>
</div>
</div>
<!--+
|end Menu
+-->
<!--+
|start content
+-->
<div id="content">
<div title="Portable Document Format" class="pdflink">
<a class="dida" href="howto-howto.pdf"><img alt="PDF -icon" src="skin/images/pdfdoc.gif" class="skin"><br>
PDF</a>
</div>
<div class="trail">Font size:
&nbsp;<input value="Reset" class="resetfont" title="Reset text" onclick="ndeSetTextSize('reset'); return false;" type="button">
&nbsp;<input value="-a" class="smallerfont" title="Shrink text" onclick="ndeSetTextSize('decr'); return false;" type="button">
&nbsp;<input value="+a" class="biggerfont" title="Enlarge text" onclick="ndeSetTextSize('incr'); return false;" type="button">
</div>
<h1>How to write a How-To</h1>
<div class="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.
</div>
<div id="minitoc-area">
<ul class="minitoc">
<li>
<a href="#Intended Audience">Intended Audience</a>
</li>
<li>
<a href="#Purpose">Purpose</a>
</li>
<li>
<a href="#Prerequisites">Prerequisites</a>
</li>
<li>
<a href="#Steps">Steps</a>
<ul class="minitoc">
<li>
<a href="#overview">Write the Overview</a>
</li>
<li>
<a href="#audience">Describe your Intended Audience</a>
</li>
<li>
<a href="#purpose">State the Purpose</a>
</li>
<li>
<a href="#prerequisites">List any Prerequisites</a>
</li>
<li>
<a href="#steps">Describe the Steps of your How-To</a>
</li>
<li>
<a href="#extension">Extend the Learning</a>
</li>
<li>
<a href="#summarize">Summarize the Entire Process</a>
</li>
<li>
<a href="#tips">Additional Tips or FAQs</a>
</li>
<li>
<a href="#references">References</a>
</li>
<li>
<a href="#contribute">Submit via the project issue tracker</a>
</li>
<li>
<a href="#feedback">Get some feedback</a>
</li>
</ul>
</li>
<li>
<a href="#Extension">Extension</a>
</li>
<li>
<a href="#Frequently Asked Questions">Frequently Asked Questions</a>
<ul class="minitoc">
<li>
<a href="#1+General+issues">1 General issues</a>
<ul class="minitoc">
<li>
<a href="#1.1+What+is+the+difference+between+a+How-To+and+a+tutorial%3F">1.1 What is the difference between a How-To and a tutorial?</a>
</li>
</ul>
</li>
<li>
<a href="#2+Style+issues">2 Style issues</a>
<ul class="minitoc">
<li>
<a href="#2.1+What+spelling+convention+should+I+follow%3F">2.1 What spelling convention should I follow?</a>
</li>
</ul>
</li>
</ul>
</li>
<li>
<a href="#Tips">Tips</a>
<ul class="minitoc">
<li>
<a href="#tip-dtd">How-To dtd</a>
</li>
</ul>
</li>
<li>
<a href="#References">References</a>
</li>
</ul>
</div>
<a name="N10013"></a><a name="Intended Audience"></a>
<h2 class="underlined_10">Intended Audience</h2>
<div class="section">
<p>
Users who are ready to share their knowledge and experiences with the
community.
</p>
</div>
<a name="N1001B"></a><a name="Purpose"></a>
<h2 class="underlined_10">Purpose</h2>
<div class="section">
<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 ensure the effectiveness of your
work.
</p>
</div>
<a name="N10023"></a><a name="Prerequisites"></a>
<h2 class="underlined_10">Prerequisites</h2>
<div class="section">
<p>
How-To authors should have:
</p>
<ul>
<li>A unique How-To topic, related to using Forrest, which fulfills a
specific need. Look at 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 document. However, we would
rather that you just make a start, as the community can help to
fine-tune the document.</li>
<li>Copy this template document "howto-howto.xml" to be modified with
your own content as necessary.</li>
<li>An understanding of the How-To document structure. Just use this
template document and you will be safe.
Make sure you run '<span class="codefrag">forrest validate-xdocs</span>' before
contributing your document.</li>
</ul>
<div class="note">
<div class="label">Note</div>
<div class="content">
See the <a href="docs_0_80/../dtdx/howto-v20.dtdx.html">DTD documentation</a> which explains
the document structure.
</div>
</div>
</div>
<a name="N10044"></a><a name="Steps"></a>
<h2 class="underlined_10">Steps</h2>
<div class="section">
<p>
Here is how to proceed.
</p>
<a name="N1004C"></a><a name="overview"></a>
<h3 class="underlined_5">Write the Overview</h3>
<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>
<a name="N10056"></a><a name="audience"></a>
<h3 class="underlined_5">Describe your Intended Audience</h3>
<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>
<a name="N10060"></a><a name="purpose"></a>
<h3 class="underlined_5">State the Purpose</h3>
<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>
<a name="N1006A"></a><a name="prerequisites"></a>
<h3 class="underlined_5">List any Prerequisites</h3>
<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>
<a name="N10074"></a><a name="steps"></a>
<h3 class="underlined_5">Describe the Steps of your How-To</h3>
<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>
<a name="N1007E"></a><a name="extension"></a>
<h3 class="underlined_5">Extend the Learning</h3>
<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>
<a name="N10088"></a><a name="summarize"></a>
<h3 class="underlined_5">Summarize the Entire Process</h3>
<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>
<a name="N10092"></a><a name="tips"></a>
<h3 class="underlined_5">Additional Tips or FAQs</h3>
<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>
<a name="N1009C"></a><a name="references"></a>
<h3 class="underlined_5">References</h3>
<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>
<a name="N100A6"></a><a name="contribute"></a>
<h3 class="underlined_5">Submit via the project issue tracker</h3>
<p>
Create an attachment for your How-To document, and submit it via the
project <a href="issues.html">issue tracker</a>.
</p>
<a name="N100B4"></a><a name="feedback"></a>
<h3 class="underlined_5">Get some feedback</h3>
<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
<a href="mail-lists.html">mailing lists</a>.
</p>
</div>
<a name="N100C2"></a><a name="Extension"></a>
<h2 class="underlined_10">Extension</h2>
<div class="section">
<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>
</div>
<a name="N100CA"></a><a name="Frequently Asked Questions"></a>
<h2 class="underlined_10">Frequently Asked Questions</h2>
<div class="section">
<a name="N100CE"></a><a name="1+General+issues"></a>
<h3 class="underlined_5">1 General issues</h3>
<a name="N100D2"></a><a name="1.1+What+is+the+difference+between+a+How-To+and+a+tutorial%3F"></a>
<h4>1.1 What is the difference between a How-To and a tutorial?</h4>
<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>
<a name="N100DA"></a><a name="2+Style+issues"></a>
<h3 class="underlined_5">2 Style issues</h3>
<a name="N100DE"></a><a name="2.1+What+spelling+convention+should+I+follow%3F"></a>
<h4>2.1 What spelling convention should I follow?</h4>
<p>
Use whatever spelling convention (American, British, etc.) that is
most intuitive to you.
</p>
</div>
<a name="N100E6"></a><a name="Tips"></a>
<h2 class="underlined_10">Tips</h2>
<div class="section">
<a name="N100EB"></a><a name="tip-dtd"></a>
<h3 class="underlined_5">How-To dtd</h3>
<p>
The document structure is likely to change at some time. Please note
that this HOWTO page is likely to change as well.
</p>
</div>
<a name="N100F5"></a><a name="References"></a>
<h2 class="underlined_10">References</h2>
<div class="section">
<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 <a href="http://www.evolt.org/article/How_To_Write_A_How_To/9741/18250/index.html">How
to Write a How-To</a> on evolt.org.</li>
<li>The Linux Documentation Project's <a href="http://www.tldp.org/HOWTO/HOWTO-INDEX/index.html">HOWTO</a>
index page provides many excellent How-To documents to inspire your
efforts.</li>
</ul>
</div>
<span class="version">0.3</span>
</div>
<!--+
|end content
+-->
<div class="clearboth">&nbsp;</div>
</div>
<div id="footer">
<!--+
|start bottomstrip
+-->
<div class="lastmodified">
<script type="text/javascript"><!--
document.write("Last Published: " + document.lastModified);
// --></script>
</div>
<div class="copyright">
Copyright &copy;
2002-2007 <a href="http://www.apache.org/licenses/">The Apache Software Foundation.</a>
</div>
<!--+
|end bottomstrip
+-->
</div>
</body>
</html>