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-faq.xml
Date Wed, 29 May 2002 19:36:42 GMT
shannon     02/05/29 12:36:42

  Modified:    src/documentation/xdocs/howto howto-author-faq.xml
  Log:
  Added sections based on experience of
  working with new authors. Added pointers
  about spellchecking, validation, doc builds.
  Added links to new How-Tos related to
  bugzilla submissions and patch preparation.
  
  Revision  Changes    Path
  1.2       +62 -21    xml-cocoon2/src/documentation/xdocs/howto/howto-author-faq.xml
  
  Index: howto-author-faq.xml
  ===================================================================
  RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/howto/howto-author-faq.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- howto-author-faq.xml	13 May 2002 18:00:48 -0000	1.1
  +++ howto-author-faq.xml	29 May 2002 19:36:42 -0000	1.2
  @@ -14,16 +14,24 @@
     <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.
  +This How-To 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.
  +Cocoon users who are ready to share their knowledge and experiences with the larger Cocoon
community. This includes users who are tired of seeing the same questions asked repeatedly
on the Cocoon users list.
   </p>
   </s1>
   
  +  <s1 title="Purpose">
  +
  +<p>
  +These guidelines are based on successful FAQ 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 apply it to the cvs.
  +</p>
  +</s1>
  +
  +
     <s1 title="Prerequisites">
   <p>
   FAQ authors should have:
  @@ -31,11 +39,9 @@
   <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">
  @@ -43,44 +49,77 @@
   Here's how to proceed.
   </p>
   
  -	<s2 title="1. Write the Question" >
  +	<s2 title="1. Obtain an FAQ topic file to edit" >
  +<p>
  +FAQs source files are organized in sets of XML files based on separate Cocoon topics. You
will find all FAQ files in src/documentation/xdocs/faq/. Select the faq topic file most related
to your question. If you can't find a related topic for your question, then create a new FAQ
file by copying an existing file, editing it, and saving it with new filename based on the
new topic.
  +</p>
  +<p>
  +If you plan to edit an existing file, make sure you are working with the most recent version.
The Cocoon project's cvs stores documentation files in multiple branches. The HEAD and release
branches should be in sync for documentation. However, should there be some unintentional
discrepancy, the HEAD branch is more likely to contain the most recently updated files. If
you have a checked-out version of the cvs HEAD branch, make sure to run a cvs update before
beginning your work on any specific file. If you don't have the cvs HEAD branch, you can obtain
a list of <link href="http://cvs.apache.org/viewcvs.cgi/*checkout*/xml-cocoon2/src/documentation/xdocs/faq/">all
current FAQ files</link> through browser-based ViewCVS.
  +</p>
  +	</s2>
  +
  +
  +	<s2 title="2. Write the Question" >
   <p>
   In one to two sentences, write your question as concisely as possible.
   </p>
   	</s2>
   
  -	<s2 title="2. Write the Answer" >
  +	<s2 title="3. 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.
  +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 How-To, tutorial, snippet, or guide.
See other How-Tos for instructions on writing such documents.
  +</p> 
  +	</s2>
  +	
  +		<s2 title="4. Review other FAQs" >
  +<p>
  +If you are working with an existing FAQ file, take some time to review the other FAQs.
Given the rapid pace of change with Cocoon, many individual FAQs become out-of-date and confusing
to new users. If you have the relevant knowledge, consider updating other FAQs for technical
errors. And if you see a few typos, please consider fixing them too.
   </p> 
   	</s2>
   
  -	<s2 title="3. Get some feedback" >
  +
  +	<s2 title="5. Get some feedback" >
  +<p>
  +Consider ask a few other Cocoon users to proofread your FAQ(s). Or, post a text version
of your FAQ to the cocoon-user list, and ask for comments. 
  +</p> 
  +	</s2>
  +	
  +	<s2 title="6. Review your work" >
   <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.
  +Consider asking someone proofread your work for embarrassing spelling or grammatical errors.
At least check your document with a spell checker before submitting it. 
   </p> 
   	</s2>
   	
  -	<!-- validate -->
  -	<s2 title="4. Validate your FAQ document" >
  +	<s2 title="7. 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" >
  +	<s2 title="8. Update any related pages" >
  +<p>
  +If you are contributing a new FAQ file, it will help committers if you also edit the FAQ
main (index.xml) and menu (book.xml) files found at src/documentation/xdocs/faq/ to include
links to your new FAQ 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 HEAD, 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="9. Prepare a patch" >
   <p>
  -Create an attachment for your FAQ document, and submit it via Bugzilla. 
  -<!-- FIXME: info and link to HOWTO Bugzilla here -->
  +If you are working with an existing FAQ file, prepare a patch before submitting. If you
created a new FAQ file, it is already a patch, at least as far as Bugzilla is concerned. However,
if you are including updated FAQ main (index.xml) and menu (book.xml) files, you will need
to create a patch for these files before submitting your work. If you don't know how to prepare
a patch, follow the instructions in <link href="howto-patch.html" >How to Prepare a
Patch.</link>
  +</p> 
  +	</s2>
  +	
  +	<s2 title="10. Submit via Bugzilla" >
  +<p>
  +Submit your FAQ 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="Extension">
  +  <s1 title="Real World Ideas for FAQs">
   <p>
  -A good way to get started writing FAQs is to scour the user list, looking for commonly
asked questions. 
  +A good way to get started writing FAQs is to scour the user list, looking for commonly
asked questions. Or, let's say you have just invested a lot of time learning and successfully
applying a Cocoon-related component or feature in your work. Perhaps you finally groked the
command line features of Cocoon or successfully configured a sitemap component. Consider sharing
this knowledge, while it is still fresh, with other users. Perhaps you are the author of some
other Cocoon document, for example, a new How-To. Consider adding a FAQ, with a short description
and link, to serve as a gateway to your contribution. 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 FAQ. Think about it.
   </p>
   	</s1>
   
  @@ -88,10 +127,11 @@
     
     <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.
  +The document structure of Cocoon's FAQ page is likely to change soon. Please note that
this How-To page is likely to change as well.
   </p>
   	</s2>
   	
  +	
   	</s1>
   
     <s1 title="References">
  @@ -102,12 +142,13 @@
   <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>
  -	
  +  <s1 title="Feedback">
  +<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>
   
   
   
  
  
  

----------------------------------------------------------------------
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