cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From shan...@apache.org
Subject cvs commit: xml-cocoon2/src/documentation/xdocs/howto howto-author-snippet.xml
Date Thu, 06 Jun 2002 16:57:55 GMT
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="shannon@apache.org"/>
    </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:shannon@apache.org">Diana
Shannon.</link>
  </p>
  	</s1>
  
  
  
  </body>
  </document>
  
  
  

----------------------------------------------------------------------
In case of troubles, e-mail:     webmaster@xml.apache.org
To unsubscribe, e-mail:          cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org


Mime
View raw message