You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Christian Grobmeier <gr...@gmail.com> on 2013/09/02 22:41:54 UTC
Documentation in general (was: Fwd: Re: Removing links from the main
page)
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.
> Ascetics count. I like the new struts2 page "http://struts.apache.org/" and
> kudos struts2 community on that.
Thanks! We are using the Apache Maven Fluido plugin here, which uses
Bootstrap (just in case you want to use it too :-))
> However when people on stackoverflow ask when should they use "%{}" being
> able to point them at the tag reference would make the most sense...
You mean, OGNL docs are lacking? You are right. I just discussed that
with a few fellows at Google Hangout.
That said, its worth to separate this into a on thread, which i did now.
Not sure if the idea to switch to a different documentation system finds
support. If it does, lets discuss what opportunities we have.
Cheers
On Mon, Sep 2, 2013 at 11:25 AM, Steven Benitez
<st...@gmail.com>wrote: > This sounds good to me. A more up to
date site would be good. > > On Monday, September 2, 2013, Christian
Grobmeier wrote: > > > Hi folks, > > > > at our main page are the
following links: > > > > http://struts.SourceForge.net/ -> pretty
outdated, last update from > > 2006 it seems > > > >
http://people.apache.org/~rubys/planet/struts -> doesn't look too good >
> for us either... > > > > http://www.ApacheBookstore.com/ -> Is this
still maintained? > > > > In general I am doubting the sense of the page
at struts.apache.org. > > As we don't maintain S1 anymore, we could move
a lot of it to S2 page, > > leaving the main page with something similar
like we have at logging: > > > > http://logging.apache.org > > > >
Questions: > > > > 1) Are you fine if I would remove the links mentioned
above? > > 2) Are you fine to move to a simpler landing page (on the
long term)? > > > > Cheers > > Christian > > > > > >
--------------------------------------------------------------------- >
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
<javascript:;> > > For additional commands, e-mail:
dev-help@struts.apache.org<javascript:;> > > > > >
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation in general (was: Fwd: Re: Removing links from the
main page)
Posted by Lukasz Lenart <lu...@apache.org>.
2013/9/3 Ken McWilliams <ke...@gmail.com>:
> 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?
No, but there are plans to do it :-)
> 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).
Anyone can contribute to the docs - just fill iCLA and you're done.
The problem is with parts that are fetched from the source code
(snippets, tag reference, etc) - then you must be a committer to
introduce a change. That's why I have started advocating to move all
snippets from source to wiki (Confluence).
> 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...
Forum? Don't get it :( What for?
> 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!
To sum up:
- wiki is already there - Confluence ->
https://cwiki.apache.org/confluence/display/WW/
- fill iCLA and you can contribute to the docs
- you can fax iCLA (as I did)
> 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.
Check here http://www.apache.org/legal/
> Another thing is versioning. Is embedding the version into the url really
> be best way? (Depending on versions guessing does not always work either...)
What you see is just our userfriendlish - each time a release is
prepared, all the docs are exported from wiki and assembled in a zip
and available for download. We expand the zip and put the contents
under version branch (2.3.x, 2.2.x, etc). Maybe it isn't the best idea
and we should simply just update in one place (/docs) and forget about
the rest - if you want to have access to all docs, download them and
expand locally, wdyt?
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
Re: Documentation in general
Posted by Ken McWilliams <ke...@gmail.com>.
Thank you Lukasz,
I have a document saying I have a "Confluence"/cwiki.apache.org account:
registered with the email address ken.mcwilliams@gmail.com and the username
Quaternion.
Sounds good, I'll certainly have some questions regarding current document
structure, might want to document those too ;) one of the motivations was
the tag reference... the "evaluated" field is _always_ false!
Regards,
Ken McWilliams
On Tue, Feb 25, 2014 at 11:56 PM, Lukasz Lenart <lu...@apache.org>wrote:
> Great! Do you have user created in Confluence already? If no please
> create one and I will assign required rights. Another thing is that I
> want to move Getting Started [1] guide from Confluence to be part of
> our website. And as the website is in Subversion (powered by Jekyll)
> so you can simple prepare patches :-)
>
> [1] https://cwiki.apache.org/confluence/display/WW/Getting+Started
> [2] http://svn.apache.org/repos/asf/struts/site/trunk/
>
>
> Regards
> --
> Łukasz
> + 48 606 323 122 http://www.lenart.org.pl/
>
> 2014-02-25 23:26 GMT+01:00 Ken McWilliams <ke...@gmail.com>:
> > Hello Devs,
> >
> > I've finally filled out and submitted the ICLA and look forward to being
> > able to contribute to the documentation (wiki) also since the demos have
> > been moved to git I look forward to inspecting the demos and possibly
> > contributing there as well.
> >
> > "please advise the project PMC that your ICLA has been filed."
> > It has been filed for: Ken McWilliams.
> >
> > Regards,
> > Ken
> >
> >
> > On Wed, Sep 4, 2013 at 3:03 AM, Lukasz Lenart <lukaszlenart@apache.org
> >wrote:
> >
> >> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> >> > Am 04.09.13 10:21, schrieb Lukasz Lenart:
> >> >> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> >> >>> Can we export the docs in some way already? How can this be done?
> >> >> Now we export docs with CXF SiteExporter but that exports to pure
> html
> >> files.
> >> >>
> >> >>
> https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
> >> >>
> >> >> There are some tools/scripts that can help but they are spread over
> >> >> Apache Svn and mostly project specific. Anyway, first we must clean
> up
> >> >> Confluence before going we that or find a concept to use the same
> with
> >> >> new docs engine (include code snippets and autogenerated files)
> >> > Nice. The CXF-Exporter looks hackable:
> >> >
> >>
> https://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/
> >> >
> >> > Maybe we have a chance to cut off the html generation and replace it
> >> > with markdown.
> >> >
> >> > How is the "generate docs from javadoc" thing done (aka Snippets)? Is
> it
> >> > a Confluence feature?
> >>
> >> Yes, it's a Confluence feature, i.e.
> >>
> >>
> {snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ParametersInterceptor}
> >>
> >> from
> >> https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14064
> >>
> >>
> >> 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
> >>
> >>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
Re: Documentation in general
Posted by Lukasz Lenart <lu...@apache.org>.
Great! Do you have user created in Confluence already? If no please
create one and I will assign required rights. Another thing is that I
want to move Getting Started [1] guide from Confluence to be part of
our website. And as the website is in Subversion (powered by Jekyll)
so you can simple prepare patches :-)
[1] https://cwiki.apache.org/confluence/display/WW/Getting+Started
[2] http://svn.apache.org/repos/asf/struts/site/trunk/
Regards
--
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/
2014-02-25 23:26 GMT+01:00 Ken McWilliams <ke...@gmail.com>:
> Hello Devs,
>
> I've finally filled out and submitted the ICLA and look forward to being
> able to contribute to the documentation (wiki) also since the demos have
> been moved to git I look forward to inspecting the demos and possibly
> contributing there as well.
>
> "please advise the project PMC that your ICLA has been filed."
> It has been filed for: Ken McWilliams.
>
> Regards,
> Ken
>
>
> On Wed, Sep 4, 2013 at 3:03 AM, Lukasz Lenart <lu...@apache.org>wrote:
>
>> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>> > Am 04.09.13 10:21, schrieb Lukasz Lenart:
>> >> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>> >>> Can we export the docs in some way already? How can this be done?
>> >> Now we export docs with CXF SiteExporter but that exports to pure html
>> files.
>> >>
>> >> https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
>> >>
>> >> There are some tools/scripts that can help but they are spread over
>> >> Apache Svn and mostly project specific. Anyway, first we must clean up
>> >> Confluence before going we that or find a concept to use the same with
>> >> new docs engine (include code snippets and autogenerated files)
>> > Nice. The CXF-Exporter looks hackable:
>> >
>> https://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/
>> >
>> > Maybe we have a chance to cut off the html generation and replace it
>> > with markdown.
>> >
>> > How is the "generate docs from javadoc" thing done (aka Snippets)? Is it
>> > a Confluence feature?
>>
>> Yes, it's a Confluence feature, i.e.
>>
>> {snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ParametersInterceptor}
>>
>> from
>> https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14064
>>
>>
>> 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
>>
>>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation in general
Posted by Ken McWilliams <ke...@gmail.com>.
Hello Devs,
I've finally filled out and submitted the ICLA and look forward to being
able to contribute to the documentation (wiki) also since the demos have
been moved to git I look forward to inspecting the demos and possibly
contributing there as well.
"please advise the project PMC that your ICLA has been filed."
It has been filed for: Ken McWilliams.
Regards,
Ken
On Wed, Sep 4, 2013 at 3:03 AM, Lukasz Lenart <lu...@apache.org>wrote:
> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> > Am 04.09.13 10:21, schrieb Lukasz Lenart:
> >> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> >>> Can we export the docs in some way already? How can this be done?
> >> Now we export docs with CXF SiteExporter but that exports to pure html
> files.
> >>
> >> https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
> >>
> >> There are some tools/scripts that can help but they are spread over
> >> Apache Svn and mostly project specific. Anyway, first we must clean up
> >> Confluence before going we that or find a concept to use the same with
> >> new docs engine (include code snippets and autogenerated files)
> > Nice. The CXF-Exporter looks hackable:
> >
> https://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/
> >
> > Maybe we have a chance to cut off the html generation and replace it
> > with markdown.
> >
> > How is the "generate docs from javadoc" thing done (aka Snippets)? Is it
> > a Confluence feature?
>
> Yes, it's a Confluence feature, i.e.
>
> {snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ParametersInterceptor}
>
> from
> https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14064
>
>
> 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
>
>
Re: Documentation in general
Posted by Lukasz Lenart <lu...@apache.org>.
2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> Am 04.09.13 10:21, schrieb Lukasz Lenart:
>> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>>> Can we export the docs in some way already? How can this be done?
>> Now we export docs with CXF SiteExporter but that exports to pure html files.
>>
>> https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
>>
>> There are some tools/scripts that can help but they are spread over
>> Apache Svn and mostly project specific. Anyway, first we must clean up
>> Confluence before going we that or find a concept to use the same with
>> new docs engine (include code snippets and autogenerated files)
> Nice. The CXF-Exporter looks hackable:
> https://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/
>
> Maybe we have a chance to cut off the html generation and replace it
> with markdown.
>
> How is the "generate docs from javadoc" thing done (aka Snippets)? Is it
> a Confluence feature?
Yes, it's a Confluence feature, i.e.
{snippet:id=description|javadoc=true|url=com.opensymphony.xwork2.interceptor.ParametersInterceptor}
from https://cwiki.apache.org/confluence/pages/editpage.action?pageId=14064
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
Re: Documentation in general
Posted by Christian Grobmeier <gr...@gmail.com>.
Am 04.09.13 10:21, schrieb Lukasz Lenart:
> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>> Can we export the docs in some way already? How can this be done?
> Now we export docs with CXF SiteExporter but that exports to pure html files.
>
> https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
>
> There are some tools/scripts that can help but they are spread over
> Apache Svn and mostly project specific. Anyway, first we must clean up
> Confluence before going we that or find a concept to use the same with
> new docs engine (include code snippets and autogenerated files)
Nice. The CXF-Exporter looks hackable:
https://svn.apache.org/repos/asf/cxf/web/src/main/java/org/apache/cxf/cwiki/
Maybe we have a chance to cut off the html generation and replace it
with markdown.
How is the "generate docs from javadoc" thing done (aka Snippets)? Is it
a Confluence feature?
>
> Regards
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation in general
Posted by Lukasz Lenart <lu...@apache.org>.
2013/9/4 Christian Grobmeier <gr...@gmail.com>:
> Can we export the docs in some way already? How can this be done?
Now we export docs with CXF SiteExporter but that exports to pure html files.
https://svn.apache.org/repos/asf/struts/struts2/trunk/assembly/pom.xml
There are some tools/scripts that can help but they are spread over
Apache Svn and mostly project specific. Anyway, first we must clean up
Confluence before going we that or find a concept to use the same with
new docs engine (include code snippets and autogenerated files)
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
Re: Documentation in general
Posted by Christian Grobmeier <gr...@gmail.com>.
Am 04.09.13 08:26, schrieb Lukasz Lenart:
> 2013/9/3 Steven Benitez <st...@gmail.com>:
>> 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/
> Good idea and we were talking about that - but first we must export
> all the docs from Confluence to markdown format, setup comments engine
> and so on - lot of work :-) But definitely is worth to engage as the
> current ApacheCMS/SvnPubSub mechanism is a bit painful when used with
> Confluence ;-) And thus allows contribute patches to documentation :-)
>
> Anyway, before we can start, docs must contain all the data - not to
> be spread throughout the source code (example snippets, tag reference)
I love Jekyll myself, +1 on that.
Can we export the docs in some way already? How can this be done?
>> 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.
> C'mon, it's just 5 sec! And opens doors to become committer :-)
>
>
> Regards
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation in general
Posted by Christian Grobmeier <gr...@gmail.com>.
Am 04.09.13 10:29, schrieb Lukasz Lenart:
> 2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>>> C'mon, it's just 5 sec! And opens doors to become committer :-)
>> Actually, it's not!
>>
>> Not everybody got a scanner or a fax round the corner. I understand it
>> is necessary, but we should not require an ICLA for typos or small
>> contributions (fixing a parameter in docs or so).
>>
>> That said, we need an ICLA, right, but we should be aware this is a
>> barrier and the difference to GitHub.
> ICLA is here to protect users so that's the difference to GitHub. I
> know plenty of companies which are rejected usage of given lib because
> of unclear legal status. IMHO it isn't a barrier if you want - you can
> ask your company to use a fax or visit post office, etc.
We don't need to discuss this further, I know what it is for.
We just need to know that potential Struts committers already have more
barriers than the average GitHub user. At least when the ICLA is on file
we need to make it as easy as possible to contribute. Compared to all
other projects I know at the ASF I think its pretty difficult to
contribute Struts
>
> Regards
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation in general
Posted by Lukasz Lenart <lu...@apache.org>.
2013/9/4 Christian Grobmeier <gr...@gmail.com>:
>> C'mon, it's just 5 sec! And opens doors to become committer :-)
> Actually, it's not!
>
> Not everybody got a scanner or a fax round the corner. I understand it
> is necessary, but we should not require an ICLA for typos or small
> contributions (fixing a parameter in docs or so).
>
> That said, we need an ICLA, right, but we should be aware this is a
> barrier and the difference to GitHub.
ICLA is here to protect users so that's the difference to GitHub. I
know plenty of companies which are rejected usage of given lib because
of unclear legal status. IMHO it isn't a barrier if you want - you can
ask your company to use a fax or visit post office, etc.
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
Re: Documentation in general
Posted by Christian Grobmeier <gr...@gmail.com>.
Am 04.09.13 08:26, schrieb Lukasz Lenart:
> 2013/9/3 Steven Benitez <st...@gmail.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.
> C'mon, it's just 5 sec! And opens doors to become committer :-)
Actually, it's not!
Not everybody got a scanner or a fax round the corner. I understand it
is necessary, but we should not require an ICLA for typos or small
contributions (fixing a parameter in docs or so).
That said, we need an ICLA, right, but we should be aware this is a
barrier and the difference to GitHub.
Cheers
>
> Regards
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Documentation in general (was: Fwd: Re: Removing links from the
main page)
Posted by Lukasz Lenart <lu...@apache.org>.
2013/9/3 Steven Benitez <st...@gmail.com>:
> 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/
Good idea and we were talking about that - but first we must export
all the docs from Confluence to markdown format, setup comments engine
and so on - lot of work :-) But definitely is worth to engage as the
current ApacheCMS/SvnPubSub mechanism is a bit painful when used with
Confluence ;-) And thus allows contribute patches to documentation :-)
Anyway, before we can start, docs must contain all the data - not to
be spread throughout the source code (example snippets, tag reference)
> 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.
C'mon, it's just 5 sec! And opens doors to become committer :-)
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
Re: Documentation in general (was: Fwd: Re: Removing links from the
main page)
Posted by Steven Benitez <st...@gmail.com>.
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 <ke...@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 <gr...@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
> >
> >
>
Re: Documentation in general (was: Fwd: Re: Removing links from the
main page)
Posted by Ken McWilliams <ke...@gmail.com>.
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 <lu...@apache.org>wrote:
> 2013/9/2 Christian Grobmeier <gr...@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
>
>
Re: Documentation in general (was: Fwd: Re: Removing links from the
main page)
Posted by Lukasz Lenart <lu...@apache.org>.
2013/9/2 Christian Grobmeier <gr...@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