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 README.txt book.xml howto-author-faq.xml howto-author-howto.xml index.xml
Date Mon, 13 May 2002 18:00:49 GMT
shannon     02/05/13 11:00:49

  Added:       src/documentation/xdocs/howto README.txt book.xml
                        howto-author-faq.xml howto-author-howto.xml
                        index.xml
  Log:
  Proposed new howto organization for content.
  Provides preliminary guidance to user content volunteers.
  Uses document dtd while howto.dtd is refined
  for CMS and Forrest concerns.
  
  Revision  Changes    Path
  1.1                  xml-cocoon2/src/documentation/xdocs/howto/README.txt
  
  Index: README.txt
  ===================================================================
  Filename conventions
  How-To files in this directory should follow the following naming convention:
  
      howto-<descriptive-name-here>.xml
  
  Use hyphens between any words which follow "howto-". 
  
  
  
  
  1.1                  xml-cocoon2/src/documentation/xdocs/howto/book.xml
  
  Index: book.xml
  ===================================================================
  <?xml version="1.0"?>
  <!DOCTYPE book PUBLIC "-//APACHE//DTD Cocoon Documentation Book V1.0//EN" "../dtd/book-cocoon-v10.dtd">
  
  <book software="Apache Cocoon" 
        title="Apache Cocoon HOWTO Documentation" 
        copyright="@year@ The Apache Software Foundation">
  
    <menu label="Navigation">
      <menu-item label="Main" href="../index.html"/>
    </menu>
  
    <menu label="How-Tos">
      <menu-item label="Index" href="index.html"/>
    </menu>
  
    <menu label="Documentation">
      <menu-item label="Author How-to" href="howto-author-howto.html"/>
      <menu-item label="Author FAQ" href="howto-author-faq.html"/>
    </menu>
    
  
  
  </book>
  
  
  
  
  
  1.1                  xml-cocoon2/src/documentation/xdocs/howto/howto-author-faq.xml
  
  Index: howto-author-faq.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 an FAQ</title>
    <authors>
     <person name="Diana Shannon" email="shannon@apache.org"/>
    </authors>
   </header>
  
   <body>
  
    <s1 title="Overview">
  
  <p>
  This HOWTO 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.
  </p>
  </s1>
  
    <s1 title="Intended Audience">
  <p>
  Cocoon users who are ready to share their knowledge and experiences with the larger Cocoon
community.
  </p>
  </s1>
  
    <s1 title="Prerequisites">
  <p>
  FAQ authors should have:
  </p>
  <ul>
  <li>A unique FAQ related to any aspect of Cocoon. Check out existing FAQs to find
a conceptual hole that your FAQ can fill.</li>
  <li>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.</li>
  <li>Currently, the Cocoon documentation project is still working out the exact details
for a FAQ dtd and template. For now, just edit the most recent version of any existing FAQ
category document, adding your own content as necessary. Make sure you use most recent version
of faq dtd to validate your FAQ before submitting. You will find it in  src/documentation/xdocs/dtd
in your cocoon distribution.</li>
  
  </ul>
  
  <!-- <p>You may also find it useful to read HOWTO Write Effectively <FIXME:
add link when available>. </p> -->  
  </s1>
  
  	<s1 title="Steps">
  <p>
  Here's how to proceed.
  </p>
  
  	<s2 title="1. Write the Question" >
  <p>
  In one to two sentences, write your question as concisely as possible.
  </p>
  	</s2>
  
  	<s2 title="2. Write the Answer" >
  <p>
  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 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 HOWTO, tutorial, snippet, or guide. See
other HOWTOs for instructions on writing such documents.
  </p> 
  	</s2>
  
  	<s2 title="3. Get some feedback" >
  <p>
  Ask a few other Cocoon users to proofread your FAQ. Or, post a text version of your FAQ
to the cocoon-user list, and ask for comments.
  </p> 
  	</s2>
  	
  	<!-- validate -->
  	<s2 title="4. Validate your FAQ document" >
  <p>
  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.
  </p> 
  	</s2>
  	
  	<s2 title="5. Submit via Bugzilla" >
  <p>
  Create an attachment for your FAQ document, and submit it via Bugzilla. 
  <!-- FIXME: info and link to HOWTO Bugzilla here -->
  </p> 
  	</s2>
  
  
  	</s1>
  
    <s1 title="Extension">
  <p>
  A good way to get started writing FAQs is to scour the user list, looking for commonly asked
questions. 
  </p>
  	</s1>
  
    <s1 title="Tips">
    
    <s2 title="FAQ dtd">
  <p>
  The document structure of Cocoon's FAQ page is likely to change soon. Please note that this
HOWTO page is likely to change as well.
  </p>
  	</s2>
  	
  	</s1>
  
    <s1 title="References">
  <p>
  FAQs mean different things to different people. For additional insight and perspectives,
check out the following.
  </p>
  	<ul>
  <li>
  Jodi Bollaert's <link href="http://www-106.ibm.com/developerworks/library/us-faq/?dwzone=usability">Mind
your FAQs</link> at IBM developerWorks.
  </li>
  
  
  	</ul>
  	
  	</s1>
  	
  
  
  
  </body>
  </document>
  
  
  
  1.1                  xml-cocoon2/src/documentation/xdocs/howto/howto-author-howto.xml
  
  Index: howto-author-howto.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 How-To</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 an effective How-To for Cocoon. The Cocoon
documentation project needs your help. Writing a Cocoon How-To is a valuable way to give back
to the community.
  </p>
  </s1>
  
    <s1 title="Intended Audience">
  <p>
  Cocoon users who are ready to share their knowledge and experiences with the larger Cocoon
community.
  </p>
  </s1>
  
    <s1 title="Prerequisites">
  <p>
  How-To authors should have:
  </p>
  <ul>
  <li>A unique How-To topic, related to using Cocoon, which fulfills a specific need.
Check out <link href="index.html">existing How-Tos</link> to find a niche for
your work. Consider posting your idea for the How-To to cocoon-user list, to make sure another
author's draft is not already in process.</li>
  <li>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.</li>
  <!-- <li>A fresh copy of How-To writing template, available from (FIXME: where?).</li>
-->
  <li>Currently, the Cocoon documentation project is still working out the exact details
for a How-To dtd and template. For now, just edit the most recent version of any existing
How-To, filling in your own content as necessary. Make sure you use most recent version of
document dtd to validate your How-To before submitting. You will find it in  src/documentation/xdocs/dtd
in your cocoon distribution.</li>
  </ul>
  
  <!-- <p>You may also find it useful to read How to Write Effectively <FIXME:
add link when available>. </p> -->  
  </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 How-To matches
their interests or needs. In a few sentences, summarize the main points of your How-To. Make
sure to include any critical definitions which will help readers evaluate the utility of your
How-To. Consider writing the overview last, after you have completed all other sections.
  </p>
  	</s2>
  
  	<s2 title="2. Describe your Intended Audience" >
  <p>
  If your How-To is targetted at a specific audience, describe it here. For example, potential
readers will have different levels of skill using Cocoon. They will also bring different areas
of expertise and backgrounds to their How-To learning experience. When you clarify your target
audience up front, you will save all other readers time and confusion. 
  </p> 
  	</s2>
  
  	<s2 title="3. State the Purpose" >
  <p>
  State the purpose of your How-To. Explain how the reader will benefit by reading it. Give
your reader an incentive or two to continue. 
  </p>
  	</s2>
  
  	<s2 title="4. List any Prerequsites" >
  <p>
  Inform your reader about any required knowledge, configuration, or resources they may need
before stepping through your How-To. Assist them in this preparation by linking to other useful
resources on the Cocoon site or the web. Helping your readers to prepare increases the likelihood
that they will continue reading your How-To.
  </p>
  	</s2>
  
  	<s2 title="5. Describe the Steps of your How-To" >
  <p>
  In a precise, step-by-step approach, walk your reader through the process. Make sure your
reader can reproduce your intended result by following your exact steps. Make the learning
process efficient by supplying sample code snippets or configuration details as necessary.
  </p>
  	</s2>
  
  	<s2 title="6. Extend the Learning" >
  <p>
  Provide your reader with a few real-world examples of how the techniques or capabilities
gained from your How-To could be applied. Reward the reader for successfully completing the
How-To with a few ideas about how it will pay off.
  </p>
  	</s2>
  
  
  	<s2 title="7. Summarize the Entire Process" >
  <p>
  In a few sentences, remind the reader what they have just learned. This helps to reinforce
the main points of your How-To.  
  </p>
  	</s2>
  
  
  	<s2 title="8. Additional Tips or FAQs" >
  <p>
  In some cases, step-by-step instructions simply aren't enough. Use this section to pass
on any other tips or frequently asked questions. Anticipating the needs of your readers will
increase the overall success of your writing effort.
  </p>
  	</s2>
  
  	<s2 title="9. References" >
  <p>
  Remember to acknowledge any third-party resources or individuals who contributed to the
development of your How-To. Consider providing links for those motivated readers who want
to learn more.
  </p>
  	</s2>
  	
  	<s2 title="10. Get some feedback" >
  <p>
  Ask a few other Cocoon users to proofread your How-To. Or, post a text version of it to
the cocoon-user list, and ask for comments.
  </p> 
  	</s2>
  	
  	<s2 title="11. Submit via Bugzilla" >
  <p>
  Create an attachment for your How-To document, and submit it via Bugzilla. 
  <!-- link to How-To Bugzilla here -->
  </p> 
  	</s2>
  
  	</s1>
  
    <s1 title="Extension">
  <p>
  Cocoon solutions can be extended to cover many different problem domains. A nearly unlimited
number of potential How-To topics, from simple to complex, are available right now, limited
only by your imagination. 
  </p>
  	</s1>
  
    <s1 title="Frequently Asked Questions">
    
    <s2 title="Q. What's the difference between a How-To and a tutorial?">
  <p>
  A. The goal of a How-To is to help the reader to accomplish a specific task with clear and
consise instructions. While tutorials may contain How-To-like instructions and content, they
also include additional background and conceptual content to help teach their readers higher
order concepts along the way. How-Tos are concerned about filling an immediate, short-term
need. Tutorials often provide long-term knowledge which can be applied across a range of needs.
  </p>
  	</s2>
  	
  	<s2 title="Q. What spelling convention should I follow?">
  <p>
  A. Use whatever spelling convention (American, British, etc.) that is most intuitive to
you.
  </p>
  
  	</s2>
  	</s1>
  	
    <s1 title="Tips">
    
    <s2 title="How-To dtd">
  <p>
  The document structure of Cocoon's How-To page is likely to change soon. Please note that
this HOWTO page is likely to change as well.
  </p>
  	</s2>
  	
  	</s1>
  
    <s1 title="References">
  <p>
  This is not the first, nor will it be the last, How-To on writing How-Tos. For other ideas
and opinions on the matter, check out the following sources.
  </p>
  	<ul>
  <li>
  Joel D. Canfield's <link href="http://www.evolt.org/article/How_To_Write_A_How_To/9741/18250/index.html">How
to Write a How-To</link> on evolt.org.
  </li>
  <li>
  The Linux Documentation Project's <link href="http://www.tldp.org/HOWTO/HOWTO-INDEX/index.html">HOWTO</link>
index page provides many excellent How-To documents to inspire your efforts.
  </li>
  
  	</ul>
  	
  	</s1>
  	
  
  
  
  </body>
  </document>
  
  
  
  1.1                  xml-cocoon2/src/documentation/xdocs/howto/index.xml
  
  Index: index.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../dtd/document-v10.dtd">
  
  <document>
  <header>
  <title>Cocoon HOWTO</title>
  <subtitle>Overview</subtitle>
  <authors>
  <person name="Diana Shannon" email="shannon@apache.org"/>
  </authors>
  </header>
  
  <body>
   
   <s1 title="Overview">
  
  <p>
  This is a collection of How-tos. The Cocooon project is actively seeking additional How-to
contributors to expand this collection. For information on how to write your own How-to, please
see <link href="howto-author-howto.html">How to write your own How-to.</link>
  </p>
  
  
   <s2 title="Documentation How-Tos">
  
  	<ul>
  <li><link href="howto-author-howto.html">How to Write a How-To</link></li>
  <li><link href="howto-author-faq.html">How to Write an FAQ</link></li>
  	</ul>
  
   </s2>
   
     <s2 title="Third Party HOWTOs">
  
  	<ul>
  <li>Perry Molendijk's <link href="http://www.cocooncenter.de/cc/documents/resources/xindice/index.html">Running
Xindice</link> HOWTO at cocooncenter.de.</li>
  <li>Bertrand Delacr&eacute;taz's <link href="http://www.cocooncenter.de/cc/documents/resources/hot-plugging/index.html">Automount</link>
HOWTO at cocooncenter.de.</li>
  <li>Perry Molendijk's <link href="http://www.cocooncenter.de/cc/documents/resources/sendmail/index.html">Sendmail
Logicsheet</link> HOWTO at cocooncenter.de.</li>
  
  <li><link href="http://www.galatea.com/flashguides/index.html">Galatea FlashGuides(TM)</link></li>
  <li><link href="http://durdo.miesto.sk/Cocoon2HowTo/index.html">Cocoon 2 How-To
Pages</link></li>
  	</ul>
  
   </s2>
  
   </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