shannon 02/05/29 12:37:38
Modified: src/documentation/xdocs/howto howto-author-howto.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.3 +54 -9
xml-cocoon2/src/documentation/xdocs/howto/howto-author-howto.xml
Index: howto-author-howto.xml
===================================================================
RCS file:
/home/cvs/xml-cocoon2/src/documentation/xdocs/howto/howto-author-howto.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- howto-author-howto.xml 17 May 2002 12:39:08 -0000 1.2
+++ howto-author-howto.xml 29 May 2002 19:37:38 -0000 1.3
@@ -18,6 +18,12 @@
</p>
</s1>
+ <s1 title="Purpose">
+<p>
+These guidelines are based on successful How-To 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="Intended Audience">
<p>
Cocoon users who are ready to share their knowledge and experiences with the
larger Cocoon community.
@@ -32,10 +38,9 @@
<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>
+<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 similar How-To, filling in your own content as necessary. For
example, some How-Tos are single pages, other span multiple pages, while others
include images. Make sure you use most recent version of document dtd to
validate any How-To file 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">
@@ -99,24 +104,52 @@
</p>
</s2>
- <s2 title="10. Get some feedback" >
+ <s2 title="10. Feedback" >
+<p>
+If you'd like to receive comments about your How-To, provide a feedback
section. Include instructions and perhaps an email address if you want users to
contact you. This helps keep your How-To current and relevant for users.
+</p>
+ </s2>
+
+ <s2 title="11. 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" >
+ <s2 title="12. Review your work" >
<p>
-Create an attachment for your How-To document, and submit it via Bugzilla.
-<!-- link to How-To Bugzilla here -->
+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>
+
+ <s2 title="13. Validate your How-To document" >
+<p>
+Use the most recent version of the document dtd to validate your How-To
content. You will find it in the src/documentation/xdocs/dtd directory.
+</p>
+ </s2>
+
+ <s2 title="14. Update any related pages" >
+<p>
+It would help committers if you also edited the How-To main (index.xml) and
menu (book.xml) files found at src/documentation/xdocs/howto/ to include links
to your new How-To. 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="15. Prepare any related patches" >
+<p>
+Any new How-To file is already a patch, at least as far as Bugzilla is
concerned. However, if you also edited the How-To 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="16. Submit via Bugzilla" >
+<p>
+Create an attachment for your How-To document, and submit it via Bugzilla.
If you don't know how to submit via Bugzilla, 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 How-Tos">
<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.
+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. Perhaps you just
successfully designed your own custom component. Consider writing a How-To
about how you did it. Let's say you finally configured an important Cocoon
feature, like logging, to your satisfaction. Share your ideas with others by
writing about it. Or maybe you just read a few short FAQs and realize you have
the knowledge already extend them with a more comprehensive How-To. 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 How-To. Think
about it.
</p>
</s1>
@@ -130,7 +163,7 @@
<s2 title="Q. What spelling convention should I follow?">
<p>
-A. Use whatever spelling convention (American, British, etc.) that is most
intuitive to you.
+A. Use whatever spelling convention (American, British, etc.) that is most
intuitive to you. More importantly, take the time to spell check your work.
</p>
</s2>
@@ -152,6 +185,12 @@
</p>
</s2>
+ <s2 title="How to spell How-To">
+<p>
+The Cocoon project's style convention is hyphenated words with word caps, as
in "How-To". Thanks for using the same convention in your work.
+</p>
+ </s2>
+
</s1>
<s1 title="References">
@@ -168,6 +207,12 @@
</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]
