This How-To describes the steps necessary to write an useful FAQ for the Cocoon documentation project. FAQs are frequently asked questions. However, for many, the word has come to mean a lot more. The Cocoon documentation project needs your help. Writing a Cocoon FAQ is a valuable way to give back to the community.

Cocoon users who are ready to share their knowledge and experiences with the larger Cocoon community. This includes users who are tired of seeing the same questions asked repeatedly on the Cocoon users list.

These guidelines are based on successful FAQ 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.

FAQ authors should have:

• A unique FAQ related to any aspect of Cocoon. Check out existing FAQs to find a conceptual hole that your FAQ can fill.
• 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.

Here's how to proceed.

FAQs source files are organized in sets of XML files based on separate Cocoon topics. You will find all FAQ files in src/documentation/xdocs/faq/. Select the faq topic file most related to your question. If you can't find a related topic for your question, then create a new FAQ file by copying an existing file, editing it, and saving it with new filename based on the new topic.

If you plan to edit an existing file, make sure you are working with the most recent version. The Cocoon project's cvs stores documentation files in multiple branches. The HEAD and release branches should be in sync for documentation. However, should there be some unintentional discrepancy, the HEAD branch is more likely to contain the most recently updated files. If you have a checked-out version of the cvs HEAD branch, make sure to run a cvs update before beginning your work on any specific file. If you don't have the cvs HEAD branch, you can obtain a list of all current FAQ files through browser-based ViewCVS.

In one to two sentences, write your question as concisely as possible.

In a few paragraphs or less, answer your question. Provide links to more detailed information within other Cocoon documentation or elsewhere on the web if available. If your answer is dependent in any way upon a specific version or deployment of Cocoon, please describe your environment. If you need more space to answer the question, consider contributing a different document to provide more comprehensive treatment of the subject. Such a document could be a How-To, tutorial, snippet, or guide. See other How-Tos for instructions on writing such documents.

If you are working with an existing FAQ file, take some time to review the other FAQs. Given the rapid pace of change with Cocoon, many individual FAQs become out-of-date and confusing to new users. If you have the relevant knowledge, consider updating other FAQs for technical errors. And if you see a few typos, please consider fixing them too.

Consider ask a few other Cocoon users to proofread your FAQ(s). Or, post a text version of your FAQ 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 FAQ dtd to validate your FAQ content. You will find it in the src/documentation/xdocs/dtd directory.

If you are contributing a new FAQ file, it will help committers if you also edit the FAQ main (index.xml) and menu (book.xml) files found at src/documentation/xdocs/faq/ to include links to your new FAQ file. 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.

If you are working with an existing FAQ file, prepare a patch before submitting. If you created a new FAQ file, it is already a patch, at least as far as Bugzilla is concerned. However, if you are including updated FAQ main (index.xml) and menu (book.xml) files, you will need to create a patch for these files before submitting your work. If you don't know how to prepare a patch, follow the instructions in How to Prepare a Patch.

Submit your FAQ file(s) as a patch via Bugzilla. If you don't know how, follow the instructions in How to Contribute a Patch via Bugzilla.

A good way to get started writing FAQs is to scour the user list, looking for commonly asked questions. Or, let's say you have just invested a lot of time learning and successfully applying a Cocoon-related component or feature in your work. Perhaps you finally groked the command line features of Cocoon or successfully configured a sitemap component. Consider sharing this knowledge, while it is still fresh, with other users. Perhaps you are the author of some other Cocoon document, for example, a new How-To. Consider adding a FAQ, with a short description and link, to serve as a gateway to your contribution. 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 FAQ. Think about it.

The document structure of Cocoon's FAQ page is likely to change soon. Please note that this How-To page is likely to change as well.

FAQs mean different things to different people. For additional insight and perspectives, check out the following.

• Jodi Bollaert's Mind your FAQs at IBM developerWorks.

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.