> From: Quinton McCombs <[EMAIL PROTECTED]> > > I would like to suggest that two sections of documentation be created. > > One section is driven entirely by user submission. This is open source - ALL sections are driven by user submission.
> It is not formatted in XML. The formatting is trivial - if you wont spend 5 minutes figuring out how it works then just submit to the list and I or someone else will pick it up. > 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. There are bunches of how-to documents in existence, the trouble is they they are either out of date, inaccurate, not detailed enough or miss some important issue. > > 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. It's easy, just do it. > > 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. All committed documentation is "Official", be it accurate or not. > > 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. Write it in plain text and submit it to the list for review. Once we are happy with it I will spend the 5 minutes it takes to apply the xdoc tags. Once you have actually looked at an xdoc formatted document you will see that there applying this formatting is a no-brainer. There are no barriers here - write the document. Cheers, Scott -- Scott Eade Backstage Technologies Pty. Ltd. http://www.backstagetech.com.au -- To unsubscribe, e-mail: <mailto:turbine-user-unsubscribe@;jakarta.apache.org> For additional commands, e-mail: <mailto:turbine-user-help@;jakarta.apache.org>
