I would like to suggest that two sections of documentation be created. One section is driven entirely by user submission. It is not formatted in XML. It is very much like a FAQ. The community already has this right now in the form of email archives. However, I would like to suggest that a web page be dedicated to this somewhere which contains only how-to type information. This should make is a little easier for people to find the information that they are looking for.
The second section would be the current type of documentation found on the jakarta site. This would have to be submitted in whatever form is required by Anakia. It would make sense that if it were easier for users to submit documentation and see that it is published for everyone else to see, they might be more likely to take a few extra minutes to document solutions that they had to research. Also, by looking at the submissions to the user supplied documentation site, it would be easier to determine where the "official" turbine documentation really need to be improved. We might even see a few people in the community who are interested specifically in improving the documentation make more progress in this area under this type of scheme. A perfect example of this is how to use transactions. I am currently migrating from 2.1 to 2.2rc1. When I wrote my code in 2.1 for transactions, I had to go through the javadocs to figure out how to accomplish the task. Not that it was very difficult but it would have been nice if a "suggested method" for using transactions was documented somewhere. In 2.2, the method for using transactions appears to have changed. I would not mind at all writing a small how-to on this little issue. However, if the requirements for me to do this is to figure out some specific format, I would be more prone to put it off until I have more time to dedicate to it. On Tue, 2002-11-12 at 09:46, Mitch Christensen wrote: > I suspect we are using Anakia for generation of the Turbine site. If so, > any documentation must be formatted in XML, per the Anakia requirements. > Can someone validate this? > > What is mechanism for submission? If I write what I believe to be a > beneficial howto, who decides that it has applicability, and incorporates it > into the Anakia tree and regenerates the site? > > Could it be that lack of a formal process in the reason there is > insufficient/outdated documentation? > > -Mitch > > -----Original Message----- > From: Quinton McCombs [mailto:qmccombs@;nequalsone.com] > Sent: Tuesday, November 12, 2002 7:30 AM > To: Turbine Users List > Subject: Re: Documentation (was: Re: Thanks) > > > Another idea for documentation could be something similar to the Linux > Documentation Project. This would allow documents of varying scope. > For example a very small how-to could be on transactions. > > A much larger how-to could be on intake or extending the turbine schema. > > > On Mon, 2002-11-11 at 18:37, Scott Eade wrote: > > > Great. For new documents we should aim for at least an outline before > we > > add them as works in progress. If you intend working on these through > to a > > level of semi-completion then you should look at the existing xdocs > and use > > that format (it is really very easy). > > > > I can't recall where the xdoc documentation resides, bit it is fairly > easy > > to follow an example - e.g.: > > > http://cvs.apache.org/viewcvs/jakarta-turbine-2/xdocs/howto/extend-user- > howt > > o.xml?rev=1.7&content-type=text/vnd.viewcvs-markup > > > > Cheers, > > > > Scott > > >Quinton McCombs< > Strategic Planner, NEqualsOne > 1800 International Park Drive > Suite 205 > Birmingham, AL 35243 > p: 205.324.8005 x121 800.466.1337 > f: 205.324.7008 > e: [EMAIL PROTECTED] > www.NEqualsOne.com > > > > -- > To unsubscribe, e-mail: <mailto:turbine-user-unsubscribe@;jakarta.apache.org> > For additional commands, e-mail: <mailto:turbine-user-help@;jakarta.apache.org> >Quinton McCombs< Strategic Planner, NEqualsOne 1800 International Park Drive Suite 205 Birmingham, AL 35243 p: 205.324.8005 x121 800.466.1337 f: 205.324.7008 e: [EMAIL PROTECTED] www.NEqualsOne.com
