Mailing-List: contact dev-help@commons.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Commons Developers List" <dev@commons.apache.org>
Received-SPF: pass (nike.apache.org: local policy)
Date: Tue, 15 Jan 2013 14:00:43 +0100
From: Gilles Sadowski <gilles@harfang.homelinux.org>
To: dev@commons.apache.org
Subject: Re: [math] User Guide needs some love
Message-ID: <20130115130043.GA23175@dusk.harfang.homelinux.org>
Mail-Followup-To: dev@commons.apache.org
References: <50F30AE9.3080405@gmail.com>
 <CAJSjvwuFyqoBt2CaUakB5n9vhehnE462W9iR5nNk26w-V-JztQ@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: 
 <CAJSjvwuFyqoBt2CaUakB5n9vhehnE462W9iR5nNk26w-V-JztQ@mail.gmail.com>
User-Agent: Mutt/1.5.21 (2010-09-15)
X-DCC-scarlet.be-Metrics: hel 20001; Body=1 Fuz1=1 Fuz2=1
X-Virus-Scanned: clamav-milter 0.97.1-exp at hel
X-Virus-Status: Clean
X-Virus-Checked: Checked by ClamAV on apache.org

On Tue, Jan 15, 2013 at 10:01:17AM +0100, Thomas Neidhart wrote:
> On Sun, Jan 13, 2013 at 8:28 PM, Phil Steitz <phil.steitz@gmail.com> wrote:
> 
> > I just fixed a couple of errors in the User Guide.  There are likely
> > lots more and some whole sections that need to be rewritten.
> > Patches are most welcome.
> >
> > One thing we might want to consider is creating separate test
> > packages for the User Guide examples.  While this was not
> > consistently done, we used to lift user guide examples from the unit
> > tests, which made sure the examples actually worked.  The problem
> > with that approach is that there is nothing to guarantee that when
> > the unit test gets updated to reflect updates / better practices,
> > the same thing happens in the corresponding User Guide example.  It
> > would be more likely for this to happen if we either annotated the
> > test cases including guide examples somehow or separated them into a
> > "userguide" test package.  We could do this incrementally, by
> > top-level package for example, as we validate and update the guide.
> > What do you think?
> >
> 
> I think a math-samples project / directory / whatever would be quite nice.
> So users could directly try out the examples from the guide without the
> need to copy & paste things from there.

Actually, what would be great to enforce consistency is to have the examples
of the user guide directly link to the code in the "userguide" part of the
test source repository, where the corresponding code would be marked with
some kind of "anchor" (that would create the anchor to be linked to in the
generated HTML).  I've no idea whether that's possible... :-}.


Regards,
Gilles

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org