I have always thought (and said a couple of times), that we should have different doc sets depending on the versions. I usually work on trunk, and I know every time I add something new to the docs(because of a new feature in trunk) it will end up confusing users of the last stable build. We use the {warning}{warning} macros to point out version differences, but I don't think it helps too much.
About the snippets, they are handy for commiters because they can update the code and forget about the wiki, but yes, it prevents users with just a CLA to fix problems. For these quick spelling/minor comment changes you can ping me in IRC and I could fix them right away. musachy On Sun, May 18, 2008 at 3:10 PM, Chase <[EMAIL PROTECTED]> wrote: > I believe there is a problem with the current guidelines and infrastructure > for maintaining the Struts 2 documentation. This is an attempt to help > everyone see the barriers and problems with the way it's setup now. > Hopefully the process can be improved. > > If you haven't already please read > http://cwiki.apache.org/confluence/display/WW/Documentation+Style+Guide#DocumentationStyleGuide-Singlesourcingwithsnippets > > As someone relatively new to Struts 2 I've spent a large amount of time > trying to read the documentation. The first documentation issue I ran into > was that the docs already covered the 2.1 tags (id vs. var) and I was trying > to use the latest GA release (2.0.11.1). There was no mention of versioning > in the docs related to this area. I asked on the mailing list and the issue > was explained right away. I assume I'm not the only person to be confused by > this so I wanted to get the docs corrected. I asked about it and got a > helpful pointer in the right direction. After getting my CLA filed and > requesting a karma upgrade I went to edit the page only to discover the > snippet macro. > > After more reading I start using subversion to create diffs and file bug > reports. I avoid the snippet macro at first until > https://issues.apache.org/struts/browse/WW-2651. Once this patch is > committed by someone I can edit the corresponding wiki page. But this is > probably also going to depend on which branch the patch is applied to and > where the snippet macro is actually pulling from. > > I'll also have no idea if this patch will break other documentation pages as > the snippet macro error reports that would be essential to anyone > maintaining the docs seem to only be viewable by Confluence/Space > administrators. See the screenshots at > http://confluence.atlassian.com/display/CONFEXT/Snippet+Plugin if you didn't > even know that this feature existed. > > Now I want to fix the broken examples in > http://cwiki.apache.org/confluence/display/WW/stringlength+validator. There > is a missing quote and the syntax is wrong for the field validator. If you > view the comments you'll notice someone already wanted to fix one of these > problems last year. To fix these problems it looks like I need to get some > XWork code changed. Hopefully XWork never stops using snippets or the Struts > 2 documentation going to be in big trouble. Depending on a 3rd party for > snippets included in the docs means that snippet error reporting is just > that much more important. And the snippet error reporting only tells you if > a snippet is missing, not if the content has changed so that it no longer > fits the documentation. > > I still want to fix the original issue of the docs lacking 2.0 and 2.1 > version information. Really what is needed here is a snippet prefix that can > be used to specify a struts20 or a struts21 snippet. Only Confluence admins > can set this up. Following the "Contact Administrators" link at the bottom > of the Apache Confluence site takes you to > http://cwiki.apache.org/confluence/administrators.action where every single > admin's contact details are hidden. > > So in short, to effectively maintain the documentation a person must: > * Create a Confluence account > * File a CLA > * Become a committer for Struts > * Become a committer for XWork > * Become a Confluence Admin > > I haven't given up on helping to fix the docs yet but I imagine that most > people would have by now. It seems that single sourcing the documentation > with the snippet macro causes more problems and headaches than it's worth. > > -Matthieu Chase Heimer > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > -- "Hey you! Would you help me to carry the stone?" Pink Floyd --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]