This How-To describes the steps necessary to write a Code Snippet. Code Snippets include small amounts of code fragments with accompanying text explanations and tips. To extend an old saying, sometimes a few, well-chosen lines of code are worth a thousand words. The Cocoon documentation project needs your help. Writing a Cocoon Code Snippet is a valuable way to give back to the community.

Cocoon users who are ready to share helpful Code Snippets with the larger Cocoon community.

These guidelines are based on successful Code Snippet 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 add it to the cvs and web site.

Code Snippet authors should have:

• A unique Code Snippet related to any aspect of Cocoon. Check out existing Code Snippets to find a conceptual hole that your Snippet can fill.
• A sufficient ability in English to describe the Snippet. 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.

An overview helps potential readers to determine quickly if a particular Code Snippet matches their interests or needs. In a few sentences, summarize the main points of your Code Snippet. Make sure to include any critical definitions which will help readers evaluate the utility of your Code Snippet. Consider writing the overview last, after you have completed all other sections.

Open source software like Cocoon can quickly change. Make it clear what version of Cocoon you used to test your Snippet. This helps prevent unnecessary reader confusion in the future, should the underlying software change.

Write the code. Be sure to use two spaces per indent. If any line exceeds 70 chars, please add manual breaks where appropriate. This prevents unnecessary page width resizing in a browser window.

Describe the Code Snippet.

Provide additional Snippets and descriptions as necessary. Users may find it easier to understand a large Code Snippet if it is broken up into smaller portions.

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

Consider asking someone proofread your work for embarrassing coding, spelling, or grammatical errors. Remember to spell check your document before submitting it.

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

If you are contributing a new Code Snippet file, it will help committers if you also edit the Code Snippet main (index.xml) and menu (book.xml) files found at src/documentation/xdocs/snippet/ to include links to your new Snippet 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, 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 Snippet file is already a patch, at least as far as Bugzilla is concerned. However, if you also edited the Snippet 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.

Submit your Snippet 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 Snippets is to look through your Cocoon-based projects for those coding gems you worked so hard to perfect. Useful snippets can come from configuration files, such as the sitemap.xmap, cocoon.xconf, logkit.conf, web.xml, and others. You could also look for Snippets in java, XSP, and XSLT files. If your Snippet answers a FAQ, consider adding a FAQ, with a short description and link, to serve as a gateway to your contribution. If you don't know how, follow the instructions in How to Author a FAQ. 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 Code Snippet. Think about it.

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

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.