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:[EMAIL PROTECTED]";>Diana Shannon.</link>
+</p>
+ </s1>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
