struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Steven Benitez <steven.beni...@gmail.com>
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).

http://jekyllrb.com/

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.

-Steven


On Tue, Sep 3, 2013 at 2:41 PM, Ken McWilliams <ken.mcwilliams@gmail.com>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" :
> 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