I completely agree! On Wed, 2002-11-13 at 21:14, Rodney Schneider wrote:
> Hi Quinton, > > I think a combination of a twiki and a decent set of xdocs would meet your > suggestions outlined below. > > Regards, > > -- Rodney > > > On Wed, 13 Nov 2002 03:03, you wrote: > > > 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 > > -- > To unsubscribe, e-mail: <mailto:turbine-user-unsubscribe@;jakarta.apache.org> > For additional commands, e-mail: <mailto:turbine-user-help@;jakarta.apache.org>
