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]
