stevenn 2002/07/12 03:36:03 Added: targets/forrest/community/howto/bugzilla-patch/skin page.css targets/forrest/community/howto/cvs-ssh/images group-logo.gif project-logo.gif targets/forrest/community/howto/cvs-ssh/skin page.css targets/forrest/community/howto/images group-logo.gif project-logo.gif targets/forrest/community/howto/skin page.css targets/forrest/community/howto/v10 howto-v10.html targets/forrest/community/howto/xmlform/images group-logo.gif project-logo.gif targets/forrest/community/howto/xmlform/skin page.css Log: update forrest website - more to come Revision Changes Path 1.1 xml-site/targets/forrest/community/howto/bugzilla-patch/skin/page.css Index: page.css =================================================================== body { background-color: #FFFFFF; margin: 0px 0px 0px 0px; font-family: Arial, Helvetica, sans-serif; font : 12px; } a:link { color: #0F3660; } a:visited { color: #009999; } a:active { color: #000066; } a:hover { color: #000066; } .menu { background-color: #4C6C8F; margin: 0px; padding: 3px 8px 5px 3px; font : 12px; } .menu a:link { color: #FFFFFF; text-decoration : none; } .menu a:visited { color: #FFFFFF; text-decoration : none; } /*.menu a:active { font-weight: bold }*/ .menu a:hover { color: #FFCC00; text-decoration : none; } .menu ul { margin: 0px 0px 0px 20px; padding: 0px; } .menu li { list-style-image: url('images/label.gif'); } .menu ul ul li .sel { list-style-image: url('images/current.gif'); } .menu ul ul li { list-style-image: url('images/page.gif'); } .content { padding: 5px 5px 5px 10px; font : small; font-size : 12px; } .content table { width: 100%; background-color: #7099C5; color: #ffffff; font-size : 12px;} .content table .caption { text-align: left; color: black; font-size : 12px; } .content table .th { text-align: center; font-size : 12px;} .content td { background-color: #f0f0ff; color: black; font-size : 12px;} .frame { margin: 5px 20px 5px 20px; font-size: 11px; } .frame .content { margin: 0px; } .note { border: solid 1px #7099C5; background-color: #f0f0ff; } .note .label { background-color: #7099C5; color: #ffffff; } .warning { border: solid 1px #D00000; background-color: #fff0f0; } .warning .label { background-color: #D00000; color: #ffffff; } .fixme { border: solid 1px #C6C600; background-color: #FAF9C3; } .fixme .label { background-color: #C6C600; color: #ffffff; } .code { border-color: #CFDCED; border-style: solid; border-width: 1px; } .highlight { background-color: yellow; } .minitoc {margin: 5px 5px 5px 40px;} 1.1 xml-site/targets/forrest/community/howto/cvs-ssh/images/group-logo.gif <> 1.1 xml-site/targets/forrest/community/howto/cvs-ssh/images/project-logo.gif <> 1.1 xml-site/targets/forrest/community/howto/cvs-ssh/skin/page.css Index: page.css =================================================================== body { background-color: #FFFFFF; margin: 0px 0px 0px 0px; font-family: Arial, Helvetica, sans-serif; font : 12px; } a:link { color: #0F3660; } a:visited { color: #009999; } a:active { color: #000066; } a:hover { color: #000066; } .menu { background-color: #4C6C8F; margin: 0px; padding: 3px 8px 5px 3px; font : 12px; } .menu a:link { color: #FFFFFF; text-decoration : none; } .menu a:visited { color: #FFFFFF; text-decoration : none; } /*.menu a:active { font-weight: bold }*/ .menu a:hover { color: #FFCC00; text-decoration : none; } .menu ul { margin: 0px 0px 0px 20px; padding: 0px; } .menu li { list-style-image: url('images/label.gif'); } .menu ul ul li .sel { list-style-image: url('images/current.gif'); } .menu ul ul li { list-style-image: url('images/page.gif'); } .content { padding: 5px 5px 5px 10px; font : small; font-size : 12px; } .content table { width: 100%; background-color: #7099C5; color: #ffffff; font-size : 12px;} .content table .caption { text-align: left; color: black; font-size : 12px; } .content table .th { text-align: center; font-size : 12px;} .content td { background-color: #f0f0ff; color: black; font-size : 12px;} .frame { margin: 5px 20px 5px 20px; font-size: 11px; } .frame .content { margin: 0px; } .note { border: solid 1px #7099C5; background-color: #f0f0ff; } .note .label { background-color: #7099C5; color: #ffffff; } .warning { border: solid 1px #D00000; background-color: #fff0f0; } .warning .label { background-color: #D00000; color: #ffffff; } .fixme { border: solid 1px #C6C600; background-color: #FAF9C3; } .fixme .label { background-color: #C6C600; color: #ffffff; } .code { border-color: #CFDCED; border-style: solid; border-width: 1px; } .highlight { background-color: yellow; } .minitoc {margin: 5px 5px 5px 40px;} 1.1 xml-site/targets/forrest/community/howto/images/group-logo.gif <> 1.1 xml-site/targets/forrest/community/howto/images/project-logo.gif <> 1.1 xml-site/targets/forrest/community/howto/skin/page.css Index: page.css =================================================================== body { background-color: #FFFFFF; margin: 0px 0px 0px 0px; font-family: Arial, Helvetica, sans-serif; font : 12px; } a:link { color: #0F3660; } a:visited { color: #009999; } a:active { color: #000066; } a:hover { color: #000066; } .menu { background-color: #4C6C8F; margin: 0px; padding: 3px 8px 5px 3px; font : 12px; } .menu a:link { color: #FFFFFF; text-decoration : none; } .menu a:visited { color: #FFFFFF; text-decoration : none; } /*.menu a:active { font-weight: bold }*/ .menu a:hover { color: #FFCC00; text-decoration : none; } .menu ul { margin: 0px 0px 0px 20px; padding: 0px; } .menu li { list-style-image: url('images/label.gif'); } .menu ul ul li .sel { list-style-image: url('images/current.gif'); } .menu ul ul li { list-style-image: url('images/page.gif'); } .content { padding: 5px 5px 5px 10px; font : small; font-size : 12px; } .content table { width: 100%; background-color: #7099C5; color: #ffffff; font-size : 12px;} .content table .caption { text-align: left; color: black; font-size : 12px; } .content table .th { text-align: center; font-size : 12px;} .content td { background-color: #f0f0ff; color: black; font-size : 12px;} .frame { margin: 5px 20px 5px 20px; font-size: 11px; } .frame .content { margin: 0px; } .note { border: solid 1px #7099C5; background-color: #f0f0ff; } .note .label { background-color: #7099C5; color: #ffffff; } .warning { border: solid 1px #D00000; background-color: #fff0f0; } .warning .label { background-color: #D00000; color: #ffffff; } .fixme { border: solid 1px #C6C600; background-color: #FAF9C3; } .fixme .label { background-color: #C6C600; color: #ffffff; } .code { border-color: #CFDCED; border-style: solid; border-width: 1px; } .highlight { background-color: yellow; } .minitoc {margin: 5px 5px 5px 40px;} 1.1 xml-site/targets/forrest/community/howto/v10/howto-v10.html Index: howto-v10.html =================================================================== How to Author a How-To
apache > xml.apache > forrest
Apache XML logoForrest logo

the xml.apache.org sites
Home
How-Tos
XML Site
 
   

How to Author a How-To

by Diana Shannon

Overview

Intended Audience

Cocoon users who are ready to share their knowledge and experiences with the larger Cocoon community.

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 insure the effectiveness of your work.

Prerequisites

How-To authors should have:

  • 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.
  • 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.
  • 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 src/documentation/xdocs/dtd in your cocoon distribution.
Note
Within Forrest, the dtd is located in src/resources/schema/dtd.

Steps

Here's how to proceed.

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.

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 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.

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.

List any Prerequsites

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.

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.

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.

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.

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.

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.

Get some feedback

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.

Submit via Bugzilla

Create an attachment for your How-To document, and submit it via Bugzilla.

Extension

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.

Frequently Asked Questions

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.

What spelling convention should I follow?

Use whatever spelling convention (American, British, etc.) that is most intuitive to you.

Tips

How-To dtd

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.

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.

Revisions

Find a problem with this document? Consider contacting the author or submitting your own revision. For instructions, read the How To Submit a Revision.

    1.1 xml-site/targets/forrest/community/howto/xmlform/images/group-logo.gif <> 1.1 xml-site/targets/forrest/community/howto/xmlform/images/project-logo.gif <> 1.1 xml-site/targets/forrest/community/howto/xmlform/skin/page.css Index: page.css =================================================================== body { background-color: #FFFFFF; margin: 0px 0px 0px 0px; font-family: Arial, Helvetica, sans-serif; font : 12px; } a:link { color: #0F3660; } a:visited { color: #009999; } a:active { color: #000066; } a:hover { color: #000066; } .menu { background-color: #4C6C8F; margin: 0px; padding: 3px 8px 5px 3px; font : 12px; } .menu a:link { color: #FFFFFF; text-decoration : none; } .menu a:visited { color: #FFFFFF; text-decoration : none; } /*.menu a:active { font-weight: bold }*/ .menu a:hover { color: #FFCC00; text-decoration : none; } .menu ul { margin: 0px 0px 0px 20px; padding: 0px; } .menu li { list-style-image: url('images/label.gif'); } .menu ul ul li .sel { list-style-image: url('images/current.gif'); } .menu ul ul li { list-style-image: url('images/page.gif'); } .content { padding: 5px 5px 5px 10px; font : small; font-size : 12px; } .content table { width: 100%; background-color: #7099C5; color: #ffffff; font-size : 12px;} .content table .caption { text-align: left; color: black; font-size : 12px; } .content table .th { text-align: center; font-size : 12px;} .content td { background-color: #f0f0ff; color: black; font-size : 12px;} .frame { margin: 5px 20px 5px 20px; font-size: 11px; } .frame .content { margin: 0px; } .note { border: solid 1px #7099C5; background-color: #f0f0ff; } .note .label { background-color: #7099C5; color: #ffffff; } .warning { border: solid 1px #D00000; background-color: #fff0f0; } .warning .label { background-color: #D00000; color: #ffffff; } .fixme { border: solid 1px #C6C600; background-color: #FAF9C3; } .fixme .label { background-color: #C6C600; color: #ffffff; } .code { border-color: #CFDCED; border-style: solid; border-width: 1px; } .highlight { background-color: yellow; } .minitoc {margin: 5px 5px 5px 40px;} --------------------------------------------------------------------- To unsubscribe, e-mail: general-cvs-unsubscribe@xml.apache.org For additional commands, e-mail: general-cvs-help@xml.apache.org