shannon 2002/06/06 09:57:55
Added: src/documentation/xdocs/howto howto-author-snippet.xml
Log:
new how-to for authoring snippets
Revision Changes Path
1.1
xml-cocoon2/src/documentation/xdocs/howto/howto-author-snippet.xml
Index: howto-author-snippet.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>How to Author a Code Snippet</title>
<authors>
<person name="Diana Shannon" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>
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.
</p>
</s1>
<s1 title="Intended Audience">
<p>
Cocoon users who are ready to share helpful Code Snippets with the larger Cocoon
community.
</p>
</s1>
<s1 title="Purpose">
<p>
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.
</p>
</s1>
<s1 title="Prerequisites">
<p>
Code Snippet authors should have:
</p>
<ul>
<li>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.</li>
<li>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.</li>
</ul>
</s1>
<s1 title="Steps">
<p>
Here's how to proceed.
</p>
<s2 title="1. Write the Overview" >
<p>
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.
</p>
</s2>
<s2 title="2. Write Version Information" >
<p>
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.
</p>
</s2>
<s2 title="3. Write the Code Snippet" >
<p>
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.
</p>
</s2>
<s2 title="4. Write the Description" >
<p>
Describe the Code Snippet.
</p>
</s2>
<s2 title="5. Iterate as Needed" >
<p>
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.
</p>
</s2>
<s2 title="6. Ask for Comments" >
<p>
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.
</p>
</s2>
<s2 title="7. Review your work" >
<p>
Consider asking someone proofread your work for embarrassing coding, spelling, or
grammatical errors. Remember to spell check your document before submitting it.
</p>
</s2>
<s2 title="8. Validate your document" >
<p>
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.
</p>
</s2>
<s2 title="9. Update any related pages" >
<p>
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 xml-cocoon2 directory, specifying docs as the build target. A docs build not only
validates your files but also checks for broken links.
</p>
</s2>
<s2 title="10. Prepare a patch" >
<p>
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 <link href="howto-patch.html"
>How to Prepare a Patch.</link>
</p>
</s2>
<s2 title="11. Submit via Bugzilla" >
<p>
Submit your Snippet file(s) as a patch via Bugzilla. If you don't know how, follow
the instructions in <link href="howto-bugzilla.html" >How to Contribute a Patch via
Bugzilla.</link>
</p>
</s2>
</s1>
<s1 title="Real World Ideas for Code Snippets">
<p>
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 <link href="howto-author-faq.html" >How to Author a FAQ.</link> 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.
</p>
</s1>
<s1 title="Tips">
<s2 title="Snippet dtd">
<p>
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.
</p>
</s2>
</s1>
<s1 title="Comments">
<p>
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, <link
href="mailto:[EMAIL PROTECTED]";>Diana Shannon.</link>
</p>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
