shannon 2002/07/03 13:25:10
Added: src/documentation/xdocs/howto howto-author-core-docs.xml
Log:
New How-To with Guidelines to
help volunteers create new
or improve existing core docs.
Written to address on feedback
on cocoon-users about the need to
improve core documentation.
Revision Changes Path
1.1
xml-cocoon2/src/documentation/xdocs/howto/howto-author-core-docs.xml
Index: howto-author-core-docs.xml
===================================================================
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN"
"../dtd/document-v10.dtd">
<document>
<header>
<title>How to Author Core Documentation</title>
<authors>
<person name="Diana Shannon" email="[EMAIL PROTECTED]"/>
</authors>
</header>
<body>
<s1 title="Overview">
<p>
This How-To describes the steps necessary to author or revise core
documentation for Cocoon. Documentation is considered "core" if it is included
in any Cocoon guide. Currently there are three guides: CTWIG, user, and
developer. Please note that this guide structure may be revised soon. As you
probably have discovered by now, many gaps exist in current Cocoon
documentation. Authoring new core documents is a valuable way contribute to the
Cocoon community.
</p>
</s1>
<s1 title="Purpose">
<p>
Writing about Cocoon is not a trivial exercise. Understanding the Cocoon CVS
and document organization takes time. In other words, many potential obstacles
stand in your way. These guidelines were written to help you make the most
productive use of your "volunteer" time. Following them not only saves your
time but also saves the time of committers who will apply your work to the CVS.
</p>
</s1>
<s1 title="Intended Audience">
<p>
Cocoon users who would like to improve Cocoon's documentation. This includes
authors, editors, proofreaders, and quality assurance testers.
</p>
</s1>
<s1 title="Prerequisites">
<ul>
<li>Spend some time familiarizing yourself with status of existing Cocoon
documents.</li>
<li>When evaluating doc-related issues, make sure you are referring to the
most recent document versions from the CVS or Cocoon web site. Please note that
sometimes the most recent version of any document will be found only in CVS
HEAD.</li>
</ul>
</s1>
<s1 title="Steps">
<p>
Here's how to proceed.
</p>
<s2 title="1. Join the cocoon-docs email list" >
<p>
Find out what documentation efforts are already in process among other users
and committers. Join the Cocoon <link href="mailto:[EMAIL PROTECTED]">Docs
List</link>.
</p>
</s2>
<s2 title="2. Find a job" >
<p>
Look through Cocoon's documentation set in order to find content holes to
fill or existing documents to improve. You don't have to be an author to
contribute: editors, proofreaders, and quality assurance testers provide vital
work as well.
</p>
</s2>
<s2 title="3. Announce your effort" >
<p>
Let others know about your efforts. Announce your plans on the cocoon-docs
list. This will help to prevent any duplication of effort. It will also attract
the interest of and valuable feedback from other users who have similar
interests or expertise in your document's subject area.</p>
</s2>
<s2 title="4. Do the work" >
<p>
Perhaps the easiest way to start a new document is to use an existing
document as a template. If you are revising an existing document, make sure you
are using the most recent copy of the document from CVS HEAD. If you aren't
working with a local CVS repository, you can access all CVS files through <link
href="http://cvs.apache.org/viewcvs.cgi/xml-cocoon2/";>ViewCVS</link>.
</p>
</s2>
<s2 title="5. Ask for help when you need it" >
<p>
Writing effectively about a "glue" framework like Cocoon, which integrates
many diverse technologies, is difficult, no doubt about it. Navigating your way
through the CVS, Bugzilla, the patch process, as well as all of the steps of
document creation can be overwhelming at first. Many of us have "been there"
already and are available to help you. Don't hesitate to ask for assistance on
cocoon-docs when you are confronted with a conceptual or technical problem you
can't solve on your own. Don't waste your precious "volunteer" time pulling
your hair out. Still, if you reach a point in your work where you are
hopelessly stuck, you can always leave concise comments in a <fixme>
element for others to fill down the road. This is in tune with open source,
community-based development. Contribute what you can, when you have an
irresistible "itch" to "scratch". Others will pick up where you left off.
</p>
</s2>
<s2 title="6. Get some feedback" >
<p>
If you are working on a new or revised document, please post a text version
of it to the cocoon-docs list to receive valuable comments from developers and
users. Again, if you have technical holes in your content, be sure to add fixme
comments to make it clear for others what particular areas you'd like for them
to address.
</p>
</s2>
<s2 title="7. Review your work" >
<p>
Look over your work for embarrassing spelling or grammatical errors. At least
check your document with a spell checker before submitting it.
</p>
</s2>
<s2 title="8. Validate your document(s)" >
<p>
Use the appropriate and most recent dtd to validate any new or revised
documents. You will find all dtds in the src/documentation/xdocs/dtd directory.
While a "docs" target (during Cocoon's build process) is capable of validating
your files, it is far more efficient to troubleshoot validation and
well-formedness problems with your own tools.
</p>
</s2>
<s2 title="9. Update any related pages" >
<p>
If your work impacts the content of other files, for example the menu file
(known as book.xml), consider updating these documents as well. You can
validate and check link targets within all your documents by performing a docs
build. If you have a working copy of the cvs HEAD, run the appropriate build
script inside the xml-cocoon2 directory, specifying docs as the build target.
Here's an example:
</p>
<source>
./build.[sh|bat] docs
</source>
</s2>
<s2 title="10. Prepare any related patches" >
<p>
Any new document file is already a patch, at least as far as Bugzilla is
concerned. However, if you also edited any existing documents, 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="11. Submit via Bugzilla" >
<p>
Create an attachment for any documents, 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="Summary">
<p>
The Cocoon documentation effort is based on the belief that open source
documents can be as first-rate as the software on which they are based.
However, such an endeavor is dependent upon vital forms of contributions from
developers and users alike. This How-To gives you the information you need to
join like-minded individuals in the effort to improve Cocoon docs. Take a
minute to imagine how advanced the Cocoon community would become if more Cocoon
users played a role in improving Cocoon docs. Think how much more we would
learn. Think how many more innovative Cocoon-based solutions we could develop,
based on our extended knowledge. Think about it.
</p>
</s1>
<s1 title="Comments">
<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>. Even better, join the
Cocoon <link href="mailto:[EMAIL PROTECTED]">Docs List</link> and share your
feedback and ideas with other people who are committed to producing high
quality Cocoon documentation!
</p>
</s1>
</body>
</document>
----------------------------------------------------------------------
In case of troubles, e-mail: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
