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]
