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]
