struts-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rene Gielen <rene.gie...@gmail.com>
Subject Re: Moving docs from the source
Date Mon, 22 Apr 2013 07:01:48 GMT
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


Mime
View raw message