You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@struts.apache.org by Lukasz Lenart <lu...@apache.org> on 2013/04/18 09:40:09 UTC
Moving docs from the source
Hi,
Right now we have a small mismatch where the docs are kept. They are
partially in Confluence and partially in a source code of a class.
Take look on that page [1] and you will find a nice looking sections
messed up with a bit ugly inlined code. The problem is that to correct
that I have to know the source code, I mean which class is included by
a snippet to render given section. So basically I must hit Edit on the
page, check the name of the class, go to IDE, change class, commit,
etc.... very long path to improve just a typo :\
My idea is to move all the descriptions into wiki and left just a
brief description of a class with a link to the docs.
[1] http://struts.apache.org/development/2.x/docs/actionmapper.html
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: Moving docs from the source
Posted by Umesh Awasthi <um...@gmail.com>.
+1
On Thu, Apr 18, 2013 at 1:10 PM, Lukasz Lenart <lu...@apache.org>wrote:
> Hi,
>
> Right now we have a small mismatch where the docs are kept. They are
> partially in Confluence and partially in a source code of a class.
> Take look on that page [1] and you will find a nice looking sections
> messed up with a bit ugly inlined code. The problem is that to correct
> that I have to know the source code, I mean which class is included by
> a snippet to render given section. So basically I must hit Edit on the
> page, check the name of the class, go to IDE, change class, commit,
> etc.... very long path to improve just a typo :\
>
> My idea is to move all the descriptions into wiki and left just a
> brief description of a class with a link to the docs.
>
> [1] http://struts.apache.org/development/2.x/docs/actionmapper.html
>
>
> 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
>
>
--
With Regards
Umesh Awasthi
http://www.travellingrants.com/
Re: Moving docs from the source
Posted by Lukasz Lenart <lu...@apache.org>.
2013/4/22 Rene Gielen <re...@gmail.com>:
> I'm not too sure that this is a net win in the end, though I see the
> (big) itch you want to scratch. We introduced the Javadoc snippets to
> remove duplication on documentation. I'm pretty sure that most users
> really appreciate that our Javadocs contain really deep information
> including examples. Also, it is much easier for a contributor to
> steadily follow a "write code with docs" workflow rather than "write
> code and please don't forget to write / align docs in wiki".
I'm quite often noticing that the docs are out of sync with
implementation, even if they are embedded in the source code vide
CompositeActionMapper.
The second thing is a look which basically doesn't look good when docs
are included via snippet - nor formatting neither code links work.
Another think is karma, we can easily grant access to wiki, just iCLA
is needed, access to repo requires more steps - first is commitment
:-)
> That said, I'm sometimes wondering if Confluence is the best way to go
> for maintaining our docs - putting aside how painful a migration could
> be. Looking over to Wicket land, where the docs are maintained as
> wiki-like markup templates which get expanded and deployed with the
> project build seems to be really straightforward and gives better
> control of such things like snippets...
Maybe you are right but I'm not so sure ...
Do you have any link or more info about Wicket-way?
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: Moving docs from the source
Posted by Rene Gielen <re...@gmail.com>.
I'm not too sure that this is a net win in the end, though I see the
(big) itch you want to scratch. We introduced the Javadoc snippets to
remove duplication on documentation. I'm pretty sure that most users
really appreciate that our Javadocs contain really deep information
including examples. Also, it is much easier for a contributor to
steadily follow a "write code with docs" workflow rather than "write
code and please don't forget to write / align docs in wiki".
That said, I'm sometimes wondering if Confluence is the best way to go
for maintaining our docs - putting aside how painful a migration could
be. Looking over to Wicket land, where the docs are maintained as
wiki-like markup templates which get expanded and deployed with the
project build seems to be really straightforward and gives better
control of such things like snippets...
- René
Am 18.04.13 09:40, schrieb Lukasz Lenart:
> Hi,
>
> Right now we have a small mismatch where the docs are kept. They are
> partially in Confluence and partially in a source code of a class.
> Take look on that page [1] and you will find a nice looking sections
> messed up with a bit ugly inlined code. The problem is that to correct
> that I have to know the source code, I mean which class is included by
> a snippet to render given section. So basically I must hit Edit on the
> page, check the name of the class, go to IDE, change class, commit,
> etc.... very long path to improve just a typo :\
>
> My idea is to move all the descriptions into wiki and left just a
> brief description of a class with a link to the docs.
>
> [1] http://struts.apache.org/development/2.x/docs/actionmapper.html
>
>
> Regards
>
--
René Gielen
http://twitter.com/rgielen
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org
Re: Moving docs from the source
Posted by Ken McWilliams <ke...@gmail.com>.
Don't really understand. In a bit of a rush if I reread it maybe it would
sink in:
If you mean to prevent the code from updating the developer guide then
great. The developer guide should contain links to the javadoc where
appropriate which of course does need to stay in sync with the code. No
content should be removed from the source files. Although adding links to
the dev guide would certainly help.
BTW if you search "sturts2 javadoc" the first page is:
http://struts.apache.org/javadoc.html ->
http://struts.apache.org/development/2.x/struts2-core/apidocs/index.html
(Broken, kind of annoying)
On Thu, Apr 18, 2013 at 2:00 AM, Christian Grobmeier <gr...@gmail.com>wrote:
> +1
>
>
> On Thu, Apr 18, 2013 at 9:40 AM, Lukasz Lenart <lu...@apache.org>
> wrote:
> > Hi,
> >
> > Right now we have a small mismatch where the docs are kept. They are
> > partially in Confluence and partially in a source code of a class.
> > Take look on that page [1] and you will find a nice looking sections
> > messed up with a bit ugly inlined code. The problem is that to correct
> > that I have to know the source code, I mean which class is included by
> > a snippet to render given section. So basically I must hit Edit on the
> > page, check the name of the class, go to IDE, change class, commit,
> > etc.... very long path to improve just a typo :\
> >
> > My idea is to move all the descriptions into wiki and left just a
> > brief description of a class with a link to the docs.
> >
> > [1] http://struts.apache.org/development/2.x/docs/actionmapper.html
> >
> >
> > 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
> >
>
>
>
> --
> http://www.grobmeier.de
> https://www.timeandbill.de
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
> For additional commands, e-mail: dev-help@struts.apache.org
>
>
Re: Moving docs from the source
Posted by Christian Grobmeier <gr...@gmail.com>.
+1
On Thu, Apr 18, 2013 at 9:40 AM, Lukasz Lenart <lu...@apache.org> wrote:
> Hi,
>
> Right now we have a small mismatch where the docs are kept. They are
> partially in Confluence and partially in a source code of a class.
> Take look on that page [1] and you will find a nice looking sections
> messed up with a bit ugly inlined code. The problem is that to correct
> that I have to know the source code, I mean which class is included by
> a snippet to render given section. So basically I must hit Edit on the
> page, check the name of the class, go to IDE, change class, commit,
> etc.... very long path to improve just a typo :\
>
> My idea is to move all the descriptions into wiki and left just a
> brief description of a class with a link to the docs.
>
> [1] http://struts.apache.org/development/2.x/docs/actionmapper.html
>
>
> 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
>
--
http://www.grobmeier.de
https://www.timeandbill.de
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@struts.apache.org
For additional commands, e-mail: dev-help@struts.apache.org