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]
