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]
