Hi Craig,
This is a good idea (and it has been discussed before). From my experience the
issue is not with doing that, but maintaining the documentation. And I would
suggest tags not branches, because that's what gets released.
When you document based on the trunk, the code most probably works... on the
trunk, so it may not work with a previous release. When changing code, it's not
always easy to know what test gets affected (if the test passes), let alone
where in the wiki it's referenced. I'd love to find a workable solution for
this.
Cheers
Hadrian
On Oct 13, 2010, at 3:45 PM, Craig Tataryn wrote:
> Just editing a few of the help documents and came across something. The
> "{snippet}" examples tend to come directly from trunk, however it's a bit
> misleading for users if they are seeing examples which work against "the
> latest and greatest" but they are stuck on a release version. A lot of "why
> isn't this working!!&&@!!! I copied the example right from the site" type
> questions arise.
>
> A lot of times, to compensate, the documentation will include "feature X
> available in versions Y.YY or later). The only time this falls apart is if
> you have a feature which has changed between versions and the snippet of code
> shown in the documentation only works with the "trunk" or "SNAPSHOT" build.
>
> For instance the example for MultiPart processing using the Jetty component
> had a feature added to it (i.e. use of getName() on the DataHandler works
> properly as of version 2.5) So even though the MultiPart feature has worked
> since 2.3, some aspects in the example don't (I updated the documentation to
> point this fact out).
>
> My question is, should we maybe only reference examples from the "current"
> release (i.e. can we use some type of variable in the {snippet} tag within
> the wiki to reference the proper branch to pull the code snippet from in SVN)
> by default? Then if you want to point specifically at an example from
> another branch you can do so by specifying the branch explicitly.
>
> Thanks,
>
> Craig.
>
> --
> Craig Tataryn
> site: http://www.basementcoders.com/
> podcast: http://www.basementcoders.com/?feed=podcast
> itunes: http://itunes.apple.com/podcast/the-basement-coders
> irc: ThaDon on freenode #basementcoders, ##wicket, #papernapkin
> twitter: craiger
>
