struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ken McWilliams <ken.mcwilli...@gmail.com>
Subject Re: Documentation in general (was: Fwd: Re: Removing links from the main page)
Date Tue, 03 Sep 2013 18:41:45 GMT
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" :
http://en.wikipedia.org/wiki/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 <lukaszlenart@apache.org>wrote:

> 2013/9/2 Christian Grobmeier <grobmeier@gmail.com>:
> > 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.
> >>
> >> http://struts.apache.org/release/2.3.x/docs/tag-reference.html
> >>
> >> 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 http://www.lenart.org.pl/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>

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