This How-To describes the steps necessary to write an effective 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.

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 and make it easy for committers to apply it to the cvs.

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

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 similar How-To, filling in your own content as necessary. For example, some How-Tos are single pages, other span multiple pages, while others include images. Make sure you use most recent version of document dtd to validate any How-To file before submitting. You will find it in src/documentation/xdocs/dtd in your cocoon distribution.

Here's how to proceed.

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.

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 of your How-To. Explain how the reader will benefit by reading it. Give your reader an incentive or two to continue.

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.

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.

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.

In a few sentences, remind the reader what they have just learned. This helps to reinforce the main points of your How-To.

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.

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.

If you'd like to receive comments about your How-To, provide a comments section. Include instructions and perhaps an email address if you want users to contact you. This helps keep your How-To current and relevant for users.

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.

Consider asking someone proofread your work for embarrassing spelling or grammatical errors. At least check your document with a spell checker before submitting it.

Use the most recent version of the document dtd to validate your How-To content. You will find it in the src/documentation/xdocs/dtd directory.

It would help committers if you also edited the How-To main (index.xml) and menu (book.xml) files found at src/documentation/xdocs/howto/ to include links to your new How-To. You can validate these files with their corresponding dtds as specified in their DOCTYPE statements. If you have a working copy of the cvs HEAD, make sure you check this additional work by performing a docs build. To do this, run the appropriate build script inside the cocoon-2.0 directory, specifying docs as the build target. A docs build not only validates your files but also checks for broken links.

Any new How-To file is already a patch, at least as far as Bugzilla is concerned. However, if you also edited the How-To main (index.xml) and menu (book.xml) files, you will need to create a patch for them before submitting all files. If you don't know how to create a patch, follow the instructions in How to Prepare a Patch.

Create an attachment for your How-To document, and submit it via Bugzilla. If you don't know how to submit via Bugzilla, follow the instructions in How to Contribute a Patch via Bugzilla.

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. Perhaps you just successfully designed your own custom component. Consider writing a How-To about how you did it. Let's say you finally configured an important Cocoon feature, like logging, to your satisfaction. Share your ideas with others by writing about it. Or maybe you just read a few short FAQs and realize you have the knowledge already extend them with a more comprehensive How-To. Take a minute to imagine how advanced the Cocoon community would become if each and every Cocoon user took the time to contribute a single, unique How-To. Think about it.

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

A. Use whatever spelling convention (American, British, etc.) that is most intuitive to you. More importantly, take the time to spell check your work.

Writing effectively about a "glue" framework like Cocoon, which integrates many diverse technologies, is difficult, no doubt about it. Navigating your way through the CVS, Bugzilla, the patch process, as well as all of the steps of document creation can be overwhelming at first. Many of us have "been there" already and are available to help you. Don't hesitate to ask for assistance on cocoon-docs when you are confronted with a conceptual or technical problem you can't solve on your own. Don't waste your precious "volunteer" time pulling your hair out. Still, if you reach a point in your work where you are hopelessly stuck, you can always leave concise comments in a <fixme> element for others to fill down the road. This is in tune with open source, community-based development. Contribute what you can, when you have an irresistible "itch" to "scratch". Others will pick up where you left off.

To start your new document, make a copy of this document that you are now reading. Use the filename convention. Edit it to suit, link it in to ./book.xml and run "build docs".

The document structure of Cocoon's How-To pages is likely to change soon. Please note that this HOWTO page is likely to change as well. However, do not worry as clever Cocoon will be able to translate the old documents to the new structure.

The Cocoon project's style convention is hyphenated words with word caps, as in "How-To". Thanks for using the same convention in your work.

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.

Care to comment on this How-To? Got another tip? Help keep this How-To relevant by passing along any useful feedback to the author, Diana Shannon.