struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Benitez <>
Subject Re: Documentation in general (was: Fwd: Re: Removing links from the main page)
Date Tue, 03 Sep 2013 20:38:21 GMT
I'm not sure that this would be a good fit for Struts2, but I'll throw the
idea out there anyway.

On my current project, we needed a way to have an internal documentation
site and I am using Jekyll, Github's open source content generator (the
same engine that powers Github Pages). The actual documentation are stored
as markdown files in Git (could be in the S2 repository).

A wiki may be better for our purposes, but I think that the barrier to
contribution needs to be re-worked. I've submitted patches to the code
before, but to contribute documentation I need to fill out a form, print
it, scan it, and email/fax it to Apache. Seems like more trouble than it's
worth, IMO.


On Tue, Sep 3, 2013 at 2:41 PM, Ken McWilliams <>wrote:

> Lukasz, not sure if autogeneration as it is done is best. Will create the
> JIRA request. Don't know about the use of the annotations, are there
> selenium tests checking the ognl evaluation of all attributes on all tags?
> ~Wrote the following in response to Christian but forgot to include the
> group:
> Wikis are a great way to maintain documentation, as you suggest there is an
> issue with openness (or lack there of) restricting contribution. I've used
> and setup both Mediawiki and Xwiki in the past. The later is quite easy to
> use and quite feature rich (also it's written in Java).
>  What type of content management system do you think would be better, forum
> perhaps? I think a forum would be a great addition. Of course it takes
> time...
>  I mention setting up wikis because we debated openness issues when doing
> so. In providing IT support we needed to support documentation specific to
> various clients. I advocated wikis, previously we were using internal web
> sites (static html pages) and wikis were a great improvement however they
> were not used as I expected them to be... I expected the wikis to be fully
> open because they were only accessible within each companies intranet. But
> my manager who was from an older generation didn't like the idea of the
> users being able to modify the documentation. There are a number of reasons
> for his view a couple such: perceiving the ability of anyone to update
> documentation as eroding our authority and perhaps being viewed as a threat
> to our ability to bill the customer for documentation are probably not
> issues that effect the struts2 project... but really there is a fear in
> uncertainty, from that uncertainty many reasons can be found (security
> being the most touted).
>  I explained that wikis provided tools to revert history, that is, a good
> wiki expects mistakes.  It can notify interested audiences in changes, such
> that they may be moderated.
>  The greatest thing about wikis is that they allow for community support.
> To be clear they allow the community to support struts2 documentation but
> what I mean is they let the struts2 documentation support the community. It
> is this later attitude which is more practical, and although it might
> provide a larger than expected knowledge base it will probably cover what
> people really care about.
>  As I tried explaining to my manager, although we write these systems we
> don't exactly know how they are used. He thought this was absurd. Sure, we
> wrote the shipping/receiving system and we know it inside out (one of many
> systems)... but there are various shippers who come to the order desk,
> different companies have different forms and there are different
> considerations which only people on the order desk are aware. It would be
> helpful if the documentation could be extended to include how data was to
> enter the application. In other words we understood the system but not the
> full impact of the system on the environment. This effect has been nicely
> summed up in biology as the "extended phenotype" :
>  Some security observations and suggestions:
>  - An fully open wiki will have detrimental mistakes made and will rarely
> suffer malicious alterations (it will happen), although this sounds bad it
> must be weighed against the good. There are simply more good people who
> will fix trivial errors and a good wiki is designed to be resilient. If
> there are more good people who will contribute than bad people who will do
> stupid things and those stupid things are trivially reverted the good will
> win out.
>  - There should be at least three levels of users: Trusted users (the group
> already trusted to work on the wiki), Registered Users (people who have
> taken the time to create an account), and Guests
>  - Only Trusted users should be allowed to modify the most visible pages.
> As much as I'd like to think no one would change the welcome page to
> "Spring-MVC Rocks!" some idiot is bound to do this and so only trusted
> users should be allowed to edit the welcome page and possibly a few others.
>  - Registered users should be able to change just about anything else.
>  - I'm an advocate of guest access, but if SSO is employed then the
> difference between guest and registered user from the amount of work on the
> part of the user that guest access can be reasonably avoided.
>  - Really in the ideal case you want to convey to a visiting user that
> should they see a spelling/grammar/obvious logic error that in 1 minute or
> less they can have it corrected.
>  - Don't know the facilities "Bootstrap" provides but being familiar with
> Xwiki, it has the ability to create "spaces", each space (in the form:
> http://domain/xwiki/space_name/page_name). Spaces can be configured with
> different default security levels for the pages created within. For
> instance all "core" pages could be in the "/core" space and only editable
> by trusted users. Pages under the "integration" space (covering spring,
> hibernate, security issues, etc) could be editable by all.
>  I would love to see more openness and yes had the tag reference pages been
> editable I would have made the corrections on those, and by this time all
> of the elements for all of the tags. As a side note, many months ago I
> printed and filled out 'The Apache Software Foundation Individual
> Contributor Licence Agreement ("Agreement") V2.0', it is sitting on my desk
> but when I went to send it my scanner was broken, I was just doing this
> from home. And I thought "Geez it's a pain to do a good deed!" and sloth
> has been the reason it has sat there, that and I've had no reason to use a
> scanner in all this time other than to send this one document!
> Why can't we agree to this agreement online? Seems kind of silly that all
> kinds of large service providers allow for the agreement of terms and
> conditions online but not Apache.
>  Another thing is versioning. Is embedding the version into the url really
> be best way? (Depending on versions guessing does not always work
> either...)
> On Tue, Sep 3, 2013 at 7:13 AM, Lukasz Lenart <
> >wrote:
> > 2013/9/2 Christian Grobmeier <>:
> > > Am 02.09.13 22:13, schrieb Ken McWilliams:
> > >> A bit off topic, but on the subject of clean up the struts2 tag
> > reference
> > >> has been out of date for ages with respect to telling you if the
> > attribute
> > >> is evaluated for ognl by default or not.
> > >>
> > >>
> > >>
> > >> Check the "if" and "property" tags, the "test" and "value" attributes
> > >> respectively are marked as "false" under the evaluated heading which
> is
> > >> clearly false. As a matter of fact I can't find one instance of "true"
> > for
> > >> any attribute under any tag!
> > >
> > > very welcome feedback. Actually I believe a Wiki is not the best tool
> > > for documentation. I am sticking to this project for a while now, but I
> > > could not tell from mind how to properly update the docs. I think if we
> > > could give the wider community a chance to easily contribute to the
> > > docs, we would have a huge win. For example, if you (Ken) would have
> the
> > > chance to change the problem you found within 2 minutes, you certainly
> > > would have done so already.
> >
> > Those docs are autogenerated during build process base on
> > StrutsTagAttribute annotation. Though only committers can change that.
> >
> >
> > Regards
> > --
> > Ɓukasz
> > + 48 606 323 122
> >
> > ---------------------------------------------------------------------
> > To unsubscribe, e-mail:
> > For additional commands, e-mail:
> >
> >

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message