How to write a How-To

How to write a How-To
0.3
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.
Table of contents
1 Intended Audience............................................................................................................................. 2
2 Purpose...............................................................................................................................................2
3 Prerequisites....................................................................................................................................... 2
4 Steps................................................................................................................................................... 2
4.1 Write the Overview......................................................................................................................2
4.2 Describe your Intended Audience................................................................................................2
4.3 State the Purpose..........................................................................................................................2
4.4 List any Prerequisites...................................................................................................................3
4.5 Describe the Steps of your How-To............................................................................................ 3
4.6 Extend the Learning.....................................................................................................................3
4.7 Summarize the Entire Process..................................................................................................... 3
4.8 Additional Tips or FAQs............................................................................................................. 3
4.9 References.................................................................................................................................... 3
4.10 Submit via the project issue tracker...........................................................................................3
4.11 Get some feedback..................................................................................................................... 3
5 Extension............................................................................................................................................3
6 Frequently Asked Questions............................................................................................................. 4
6.1 1 General issues........................................................................................................................... 4
6.2 2 Style issues................................................................................................................................4
7 Tips.................................................................................................................................................... 4
7.1 How-To dtd.................................................................................................................................. 4
8 References..........................................................................................................................................4
Copyright © 2002 The Apache Software Foundation. All rights reserved.

---

How to write a How-To
1 Intended Audience
Users who are ready to share their knowledge and experiences with the community.
2 Purpose
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.
3 Prerequisites
How-To authors should have:
•
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.
•
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.
•
Copy this template document "howto-howto.xml" to be modified with your own content as
necessary.
•
An understanding of the How-To document structure. Just use this template document and you will
be safe. Make sure you run 'forrest validate-xdocs' before contributing your document.
Note:
See the DTD documentation which explains the document structure.
4 Steps
Here is how to proceed.
4.1 Write the Overview
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.
4.2 Describe your Intended Audience
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.
4.3 State the Purpose
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.
Copyright © 2002 The Apache Software Foundation. All rights reserved.
Page 2/4

---

How to write a How-To
4.4 List any Prerequisites
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.
4.5 Describe the Steps of your How-To
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.
4.6 Extend the Learning
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.
4.7 Summarize the Entire Process
In a few sentences, remind the reader what they have just learned. This helps to reinforce the main
points of your How-To.
4.8 Additional Tips or FAQs
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.
4.9 References
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.
4.10 Submit via the project issue tracker
Create an attachment for your How-To document, and submit it via the project issue tracker.
4.11 Get some feedback
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 mailing lists.
5 Extension
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.
Copyright © 2002 The Apache Software Foundation. All rights reserved.
Page 3/4

---

How to write a How-To
6 Frequently Asked Questions
6.1 1 General issues
6.1.1 1.1 What is the difference between a How-To and a tutorial?
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.
6.2 2 Style issues
6.2.1 2.1 What spelling convention should I follow?
Use whatever spelling convention (American, British, etc.) that is most intuitive to you.
7 Tips
7.1 How-To dtd
The document structure is likely to change at some time. Please note that this HOWTO page is likely
to change as well.
8 References
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.
•
Joel D. Canfield's How to Write a How-To on evolt.org.
•
The Linux Documentation Project's HOWTO index page provides many excellent How-To
documents to inspire your efforts.
Copyright © 2002 The Apache Software Foundation. All rights reserved.
Page 4/4

---

Document Outline

• Table of contents
• 1 Intended Audience
• 2 Purpose
• 3 Prerequisites
• 4 Steps
  • 4.1 Write the Overview
  • 4.2 Describe your Intended Audience
  • 4.3 State the Purpose
  • 4.4 List any Prerequisites
  • 4.5 Describe the Steps of your How-To
  • 4.6 Extend the Learning
  • 4.7 Summarize the Entire Process
  • 4.8 Additional Tips or FAQs
  • 4.9 References
  • 4.10 Submit via the project issue tracker
  • 4.11 Get some feedback
• 5 Extension
• 6 Frequently Asked Questions
  • 6.1 1 General issues
    • 6.1.1 1.1 What is the difference between a How-To and a tutorial?
  • 6.2 2 Style issues
    • 6.2.1 2.1 What spelling convention should I follow?
• 7 Tips
  • 7.1 How-To dtd
• 8 References

---