You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Andreas Opitz <ma...@googlemail.com> on 2014/02/11 14:56:54 UTC
Question reagarding documentation
Hi Struts Community,
last year I was on a Strutsathon in Augsburg. During this event we talked
as well about the documentation and how new user would use the documents to
dive into the world of struts.
Before this event I never worked with struts so it was quite intressting
how I can get familiar with struts and how the documentions would help me.
At that point I recongnized that struts has more than one wiki. Christian
and Rene explained this to me and we came up with the idea to improve this
part.
The initial idea was to create a maven plugin which will extract the
snippets out of the JavaDoc part of the source code. This plugin should be
a part of the site lifecycle.
Are you still using some wikis to create the documentation? And is it still
required to extract the snippets?
I am just asking hence I would like to implement this plugin. Just as a
side node I am not a maven expert this would be my first plugin and
appreaicate each feedback that I would get for this plugin.
Best regards,
Andreas
Re: Question reagarding documentation
Posted by Lukasz Lenart <lu...@apache.org>.
2014-02-11 16:08 GMT+01:00 Andreas Opitz <ma...@googlemail.com>:
> What was the reason to put the snippets into the Javadocs?
Version control and one point of reference
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: Question reagarding documentation
Posted by Lukasz Lenart <lu...@apache.org>.
Hi,
I have started moving snippets from code to Wiki. This is also needed
to properly export wiki as html - current version of Confluence
doesn't recognise snippet macro and treats it as a old wiki content,
but thus can be changed in the future.
So if you work on some Java code in Struts, please also move snippets
to appropriate wiki page.
Thanks in advance & Regards
--
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/
2014-02-20 14:25 GMT+01:00 Dave Newton <da...@gmail.com>:
> +1(00)
>
>
> On Thu, Feb 20, 2014 at 3:04 AM, Lukasz Lenart <lu...@apache.org>wrote:
>
>> Yes, I think wiki/html is the proper format here - all other projects
>> doing the same and I don't see complains about that. Maybe I'm wrong
>> but I opt to move snippets with examples and explanations to wiki.
>>
>> The main problem with out current documentation is scale - it's very
>> large, there should simple step-by-step tutorial with links to wiki
>> pages with more details on given topic.
>>
>>
>> Regards
>> --
>> Łukasz
>> + 48 606 323 122 http://www.lenart.org.pl/
>>
>> 2014-02-11 16:12 GMT+01:00 Dave Newton <da...@gmail.com>:
>> > So we could pull them in via snippets.
>> >
>> > I'd rather see examples be either in tests, separate files, or just
>> normal
>> > documentation (e.g., wiki).
>> >
>> > Dave
>> >
>> >
>> >
>> > On Tue, Feb 11, 2014 at 10:08 AM, Andreas Opitz <manyofh@googlemail.com
>> >wrote:
>> >
>> >> What was the reason to put the snippets into the Javadocs?
>> >> Am 11.02.2014 15:25 schrieb "Dave Newton" <da...@gmail.com>:
>> >>
>> >> > Just for the record (again), I'm against putting documentation in the
>> >> > Javadocs.
>> >> >
>> >> > It makes the Javadocs illegible when being read as Javadocs and bloats
>> >> them
>> >> > well beyond the point of usefulness.
>> >> >
>> >> >
>> >> > On Tue, Feb 11, 2014 at 8:56 AM, Andreas Opitz <
>> manyofh@googlemail.com
>> >> > >wrote:
>> >> >
>> >> > > Hi Struts Community,
>> >> > >
>> >> > > last year I was on a Strutsathon in Augsburg. During this event we
>> >> talked
>> >> > > as well about the documentation and how new user would use the
>> >> documents
>> >> > to
>> >> > > dive into the world of struts.
>> >> > >
>> >> > > Before this event I never worked with struts so it was quite
>> >> intressting
>> >> > > how I can get familiar with struts and how the documentions would
>> help
>> >> > me.
>> >> > > At that point I recongnized that struts has more than one wiki.
>> >> Christian
>> >> > > and Rene explained this to me and we came up with the idea to
>> improve
>> >> > this
>> >> > > part.
>> >> > >
>> >> > > The initial idea was to create a maven plugin which will extract the
>> >> > > snippets out of the JavaDoc part of the source code. This plugin
>> should
>> >> > be
>> >> > > a part of the site lifecycle.
>> >> > >
>> >> > >
>> >> > > Are you still using some wikis to create the documentation? And is
>> it
>> >> > still
>> >> > > required to extract the snippets?
>> >> > > I am just asking hence I would like to implement this plugin. Just
>> as a
>> >> > > side node I am not a maven expert this would be my first plugin and
>> >> > > appreaicate each feedback that I would get for this plugin.
>> >> > >
>> >> > > Best regards,
>> >> > > Andreas
>> >> > >
>> >> >
>> >> >
>> >> >
>> >> > --
>> >> > e: davelnewton@gmail.com
>> >> > m: 908-380-8699
>> >> > s: davelnewton_skype
>> >> > t: @dave_newton <https://twitter.com/dave_newton>
>> >> > b: Bucky Bits <http://buckybits.blogspot.com/>
>> >> > g: davelnewton <https://github.com/davelnewton>
>> >> > so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
>> >> >
>> >>
>> >
>> >
>> >
>> > --
>> > e: davelnewton@gmail.com
>> > m: 908-380-8699
>> > s: davelnewton_skype
>> > t: @dave_newton <https://twitter.com/dave_newton>
>> > b: Bucky Bits <http://buckybits.blogspot.com/>
>> > g: davelnewton <https://github.com/davelnewton>
>> > so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
>>
>> ---------------------------------------------------------------------
>> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
>> For additional commands, e-mail: dev-help@struts.apache.org
>>
>>
>
>
> --
> e: davelnewton@gmail.com
> m: 908-380-8699
> s: davelnewton_skype
> t: @dave_newton <https://twitter.com/dave_newton>
> b: Bucky Bits <http://buckybits.blogspot.com/>
> g: davelnewton <https://github.com/davelnewton>
> so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Question reagarding documentation
Posted by Dave Newton <da...@gmail.com>.
+1(00)
On Thu, Feb 20, 2014 at 3:04 AM, Lukasz Lenart <lu...@apache.org>wrote:
> Yes, I think wiki/html is the proper format here - all other projects
> doing the same and I don't see complains about that. Maybe I'm wrong
> but I opt to move snippets with examples and explanations to wiki.
>
> The main problem with out current documentation is scale - it's very
> large, there should simple step-by-step tutorial with links to wiki
> pages with more details on given topic.
>
>
> Regards
> --
> Łukasz
> + 48 606 323 122 http://www.lenart.org.pl/
>
> 2014-02-11 16:12 GMT+01:00 Dave Newton <da...@gmail.com>:
> > So we could pull them in via snippets.
> >
> > I'd rather see examples be either in tests, separate files, or just
> normal
> > documentation (e.g., wiki).
> >
> > Dave
> >
> >
> >
> > On Tue, Feb 11, 2014 at 10:08 AM, Andreas Opitz <manyofh@googlemail.com
> >wrote:
> >
> >> What was the reason to put the snippets into the Javadocs?
> >> Am 11.02.2014 15:25 schrieb "Dave Newton" <da...@gmail.com>:
> >>
> >> > Just for the record (again), I'm against putting documentation in the
> >> > Javadocs.
> >> >
> >> > It makes the Javadocs illegible when being read as Javadocs and bloats
> >> them
> >> > well beyond the point of usefulness.
> >> >
> >> >
> >> > On Tue, Feb 11, 2014 at 8:56 AM, Andreas Opitz <
> manyofh@googlemail.com
> >> > >wrote:
> >> >
> >> > > Hi Struts Community,
> >> > >
> >> > > last year I was on a Strutsathon in Augsburg. During this event we
> >> talked
> >> > > as well about the documentation and how new user would use the
> >> documents
> >> > to
> >> > > dive into the world of struts.
> >> > >
> >> > > Before this event I never worked with struts so it was quite
> >> intressting
> >> > > how I can get familiar with struts and how the documentions would
> help
> >> > me.
> >> > > At that point I recongnized that struts has more than one wiki.
> >> Christian
> >> > > and Rene explained this to me and we came up with the idea to
> improve
> >> > this
> >> > > part.
> >> > >
> >> > > The initial idea was to create a maven plugin which will extract the
> >> > > snippets out of the JavaDoc part of the source code. This plugin
> should
> >> > be
> >> > > a part of the site lifecycle.
> >> > >
> >> > >
> >> > > Are you still using some wikis to create the documentation? And is
> it
> >> > still
> >> > > required to extract the snippets?
> >> > > I am just asking hence I would like to implement this plugin. Just
> as a
> >> > > side node I am not a maven expert this would be my first plugin and
> >> > > appreaicate each feedback that I would get for this plugin.
> >> > >
> >> > > Best regards,
> >> > > Andreas
> >> > >
> >> >
> >> >
> >> >
> >> > --
> >> > e: davelnewton@gmail.com
> >> > m: 908-380-8699
> >> > s: davelnewton_skype
> >> > t: @dave_newton <https://twitter.com/dave_newton>
> >> > b: Bucky Bits <http://buckybits.blogspot.com/>
> >> > g: davelnewton <https://github.com/davelnewton>
> >> > so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
> >> >
> >>
> >
> >
> >
> > --
> > e: davelnewton@gmail.com
> > m: 908-380-8699
> > s: davelnewton_skype
> > t: @dave_newton <https://twitter.com/dave_newton>
> > b: Bucky Bits <http://buckybits.blogspot.com/>
> > g: davelnewton <https://github.com/davelnewton>
> > so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
--
e: davelnewton@gmail.com
m: 908-380-8699
s: davelnewton_skype
t: @dave_newton <https://twitter.com/dave_newton>
b: Bucky Bits <http://buckybits.blogspot.com/>
g: davelnewton <https://github.com/davelnewton>
so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
Re: Question reagarding documentation
Posted by Lukasz Lenart <lu...@apache.org>.
Yes, I think wiki/html is the proper format here - all other projects
doing the same and I don't see complains about that. Maybe I'm wrong
but I opt to move snippets with examples and explanations to wiki.
The main problem with out current documentation is scale - it's very
large, there should simple step-by-step tutorial with links to wiki
pages with more details on given topic.
Regards
--
Łukasz
+ 48 606 323 122 http://www.lenart.org.pl/
2014-02-11 16:12 GMT+01:00 Dave Newton <da...@gmail.com>:
> So we could pull them in via snippets.
>
> I'd rather see examples be either in tests, separate files, or just normal
> documentation (e.g., wiki).
>
> Dave
>
>
>
> On Tue, Feb 11, 2014 at 10:08 AM, Andreas Opitz <ma...@googlemail.com>wrote:
>
>> What was the reason to put the snippets into the Javadocs?
>> Am 11.02.2014 15:25 schrieb "Dave Newton" <da...@gmail.com>:
>>
>> > Just for the record (again), I'm against putting documentation in the
>> > Javadocs.
>> >
>> > It makes the Javadocs illegible when being read as Javadocs and bloats
>> them
>> > well beyond the point of usefulness.
>> >
>> >
>> > On Tue, Feb 11, 2014 at 8:56 AM, Andreas Opitz <manyofh@googlemail.com
>> > >wrote:
>> >
>> > > Hi Struts Community,
>> > >
>> > > last year I was on a Strutsathon in Augsburg. During this event we
>> talked
>> > > as well about the documentation and how new user would use the
>> documents
>> > to
>> > > dive into the world of struts.
>> > >
>> > > Before this event I never worked with struts so it was quite
>> intressting
>> > > how I can get familiar with struts and how the documentions would help
>> > me.
>> > > At that point I recongnized that struts has more than one wiki.
>> Christian
>> > > and Rene explained this to me and we came up with the idea to improve
>> > this
>> > > part.
>> > >
>> > > The initial idea was to create a maven plugin which will extract the
>> > > snippets out of the JavaDoc part of the source code. This plugin should
>> > be
>> > > a part of the site lifecycle.
>> > >
>> > >
>> > > Are you still using some wikis to create the documentation? And is it
>> > still
>> > > required to extract the snippets?
>> > > I am just asking hence I would like to implement this plugin. Just as a
>> > > side node I am not a maven expert this would be my first plugin and
>> > > appreaicate each feedback that I would get for this plugin.
>> > >
>> > > Best regards,
>> > > Andreas
>> > >
>> >
>> >
>> >
>> > --
>> > e: davelnewton@gmail.com
>> > m: 908-380-8699
>> > s: davelnewton_skype
>> > t: @dave_newton <https://twitter.com/dave_newton>
>> > b: Bucky Bits <http://buckybits.blogspot.com/>
>> > g: davelnewton <https://github.com/davelnewton>
>> > so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
>> >
>>
>
>
>
> --
> e: davelnewton@gmail.com
> m: 908-380-8699
> s: davelnewton_skype
> t: @dave_newton <https://twitter.com/dave_newton>
> b: Bucky Bits <http://buckybits.blogspot.com/>
> g: davelnewton <https://github.com/davelnewton>
> so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Question reagarding documentation
Posted by Dave Newton <da...@gmail.com>.
So we could pull them in via snippets.
I'd rather see examples be either in tests, separate files, or just normal
documentation (e.g., wiki).
Dave
On Tue, Feb 11, 2014 at 10:08 AM, Andreas Opitz <ma...@googlemail.com>wrote:
> What was the reason to put the snippets into the Javadocs?
> Am 11.02.2014 15:25 schrieb "Dave Newton" <da...@gmail.com>:
>
> > Just for the record (again), I'm against putting documentation in the
> > Javadocs.
> >
> > It makes the Javadocs illegible when being read as Javadocs and bloats
> them
> > well beyond the point of usefulness.
> >
> >
> > On Tue, Feb 11, 2014 at 8:56 AM, Andreas Opitz <manyofh@googlemail.com
> > >wrote:
> >
> > > Hi Struts Community,
> > >
> > > last year I was on a Strutsathon in Augsburg. During this event we
> talked
> > > as well about the documentation and how new user would use the
> documents
> > to
> > > dive into the world of struts.
> > >
> > > Before this event I never worked with struts so it was quite
> intressting
> > > how I can get familiar with struts and how the documentions would help
> > me.
> > > At that point I recongnized that struts has more than one wiki.
> Christian
> > > and Rene explained this to me and we came up with the idea to improve
> > this
> > > part.
> > >
> > > The initial idea was to create a maven plugin which will extract the
> > > snippets out of the JavaDoc part of the source code. This plugin should
> > be
> > > a part of the site lifecycle.
> > >
> > >
> > > Are you still using some wikis to create the documentation? And is it
> > still
> > > required to extract the snippets?
> > > I am just asking hence I would like to implement this plugin. Just as a
> > > side node I am not a maven expert this would be my first plugin and
> > > appreaicate each feedback that I would get for this plugin.
> > >
> > > Best regards,
> > > Andreas
> > >
> >
> >
> >
> > --
> > e: davelnewton@gmail.com
> > m: 908-380-8699
> > s: davelnewton_skype
> > t: @dave_newton <https://twitter.com/dave_newton>
> > b: Bucky Bits <http://buckybits.blogspot.com/>
> > g: davelnewton <https://github.com/davelnewton>
> > so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
> >
>
--
e: davelnewton@gmail.com
m: 908-380-8699
s: davelnewton_skype
t: @dave_newton <https://twitter.com/dave_newton>
b: Bucky Bits <http://buckybits.blogspot.com/>
g: davelnewton <https://github.com/davelnewton>
so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
Re: Question reagarding documentation
Posted by Andreas Opitz <ma...@googlemail.com>.
What was the reason to put the snippets into the Javadocs?
Am 11.02.2014 15:25 schrieb "Dave Newton" <da...@gmail.com>:
> Just for the record (again), I'm against putting documentation in the
> Javadocs.
>
> It makes the Javadocs illegible when being read as Javadocs and bloats them
> well beyond the point of usefulness.
>
>
> On Tue, Feb 11, 2014 at 8:56 AM, Andreas Opitz <manyofh@googlemail.com
> >wrote:
>
> > Hi Struts Community,
> >
> > last year I was on a Strutsathon in Augsburg. During this event we talked
> > as well about the documentation and how new user would use the documents
> to
> > dive into the world of struts.
> >
> > Before this event I never worked with struts so it was quite intressting
> > how I can get familiar with struts and how the documentions would help
> me.
> > At that point I recongnized that struts has more than one wiki. Christian
> > and Rene explained this to me and we came up with the idea to improve
> this
> > part.
> >
> > The initial idea was to create a maven plugin which will extract the
> > snippets out of the JavaDoc part of the source code. This plugin should
> be
> > a part of the site lifecycle.
> >
> >
> > Are you still using some wikis to create the documentation? And is it
> still
> > required to extract the snippets?
> > I am just asking hence I would like to implement this plugin. Just as a
> > side node I am not a maven expert this would be my first plugin and
> > appreaicate each feedback that I would get for this plugin.
> >
> > Best regards,
> > Andreas
> >
>
>
>
> --
> e: davelnewton@gmail.com
> m: 908-380-8699
> s: davelnewton_skype
> t: @dave_newton <https://twitter.com/dave_newton>
> b: Bucky Bits <http://buckybits.blogspot.com/>
> g: davelnewton <https://github.com/davelnewton>
> so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>
>
Re: Question reagarding documentation
Posted by Dave Newton <da...@gmail.com>.
Just for the record (again), I'm against putting documentation in the
Javadocs.
It makes the Javadocs illegible when being read as Javadocs and bloats them
well beyond the point of usefulness.
On Tue, Feb 11, 2014 at 8:56 AM, Andreas Opitz <ma...@googlemail.com>wrote:
> Hi Struts Community,
>
> last year I was on a Strutsathon in Augsburg. During this event we talked
> as well about the documentation and how new user would use the documents to
> dive into the world of struts.
>
> Before this event I never worked with struts so it was quite intressting
> how I can get familiar with struts and how the documentions would help me.
> At that point I recongnized that struts has more than one wiki. Christian
> and Rene explained this to me and we came up with the idea to improve this
> part.
>
> The initial idea was to create a maven plugin which will extract the
> snippets out of the JavaDoc part of the source code. This plugin should be
> a part of the site lifecycle.
>
>
> Are you still using some wikis to create the documentation? And is it still
> required to extract the snippets?
> I am just asking hence I would like to implement this plugin. Just as a
> side node I am not a maven expert this would be my first plugin and
> appreaicate each feedback that I would get for this plugin.
>
> Best regards,
> Andreas
>
--
e: davelnewton@gmail.com
m: 908-380-8699
s: davelnewton_skype
t: @dave_newton <https://twitter.com/dave_newton>
b: Bucky Bits <http://buckybits.blogspot.com/>
g: davelnewton <https://github.com/davelnewton>
so: Dave Newton <http://stackoverflow.com/users/438992/dave-newton>