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]
