You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by Gilles <gi...@harfang.homelinux.org> on 2015/01/14 02:24:13 UTC
[Math] Creating reports to be included in the user guide
Hello.
Now that we can run the code located in the "src/userguide"
directory, I'd propose that some examples be written that
produce various reports for inclusion in the user guide.
A good starting point would be to move
o.a.c.m.util.FastMathTestPerformance
from the "src/test" directory to "src/userguide".
Rationale: it's not really a test but actually a benchmark
that's only useful through _looking_ at the output.
Any objection?
Gilles
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Creating reports to be included in the user guide
Posted by Phil Steitz <ph...@gmail.com>.
On 1/14/15 7:03 AM, Gilles wrote:
> On Tue, 13 Jan 2015 20:25:53 -0700, Phil Steitz wrote:
>> On 1/13/15 6:24 PM, Gilles wrote:
>>> Hello.
>>>
>>> Now that we can run the code located in the "src/userguide"
>>> directory, I'd propose that some examples be written that
>>> produce various reports for inclusion in the user guide.
>>>
>>> A good starting point would be to move
>>> o.a.c.m.util.FastMathTestPerformance
>>> from the "src/test" directory to "src/userguide".
>>>
>>> Rationale: it's not really a test but actually a benchmark
>>> that's only useful through _looking_ at the output.
>>
>> Why does the report itself belong in the user guide? Does it help
>> users make better decisions about how to use [math]? That is what
>> the User Guide is for - to help people find things and learn how to
>> use the software. If the performance tests help make decisions,
>> then fine; if not they should not be reproduced in the guide. Or
>> are you just suggesting we move the code there so it is easier to
>> execute?
>
> A table that quantitatively backs the claim that FastMath is a
> faster and more accurate replacement for Math is (IM not so HO)
> totally relevant to help users decide whether they should find
> and replace every occurrence in their applications.[1]
>
> That said, if you feel strongly that the user guide is not the
> best place for something like a "Commons Math Facts" chapter,
> we could create another document.
Probably belongs somewhere else on the web site. Also will need to
be updated periodically. I guess that is your point below.
>
> The second reason is practical, indeed: it will be easier to
> write and run something there that will produce an appropriately
> formatted[2] output without introducing spurious dependencies in
> the "test" part of the repository.
Fine by me.
Phil
>
>
> Gilles
>
> [1] I know a distinctive case where users passed on it because
> some unit tests failed as a result of the change, and no
> advantage was prominent enough to warrant investigation.
> [2] Suggestions welcome.
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Creating reports to be included in the user guide
Posted by Gilles <gi...@harfang.homelinux.org>.
On Tue, 13 Jan 2015 20:25:53 -0700, Phil Steitz wrote:
> On 1/13/15 6:24 PM, Gilles wrote:
>> Hello.
>>
>> Now that we can run the code located in the "src/userguide"
>> directory, I'd propose that some examples be written that
>> produce various reports for inclusion in the user guide.
>>
>> A good starting point would be to move
>> o.a.c.m.util.FastMathTestPerformance
>> from the "src/test" directory to "src/userguide".
>>
>> Rationale: it's not really a test but actually a benchmark
>> that's only useful through _looking_ at the output.
>
> Why does the report itself belong in the user guide? Does it help
> users make better decisions about how to use [math]? That is what
> the User Guide is for - to help people find things and learn how to
> use the software. If the performance tests help make decisions,
> then fine; if not they should not be reproduced in the guide. Or
> are you just suggesting we move the code there so it is easier to
> execute?
A table that quantitatively backs the claim that FastMath is a
faster and more accurate replacement for Math is (IM not so HO)
totally relevant to help users decide whether they should find
and replace every occurrence in their applications.[1]
That said, if you feel strongly that the user guide is not the
best place for something like a "Commons Math Facts" chapter,
we could create another document.
The second reason is practical, indeed: it will be easier to
write and run something there that will produce an appropriately
formatted[2] output without introducing spurious dependencies in
the "test" part of the repository.
Gilles
[1] I know a distinctive case where users passed on it because
some unit tests failed as a result of the change, and no
advantage was prominent enough to warrant investigation.
[2] Suggestions welcome.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org
Re: [Math] Creating reports to be included in the user guide
Posted by Phil Steitz <ph...@gmail.com>.
On 1/13/15 6:24 PM, Gilles wrote:
> Hello.
>
> Now that we can run the code located in the "src/userguide"
> directory, I'd propose that some examples be written that
> produce various reports for inclusion in the user guide.
>
> A good starting point would be to move
> o.a.c.m.util.FastMathTestPerformance
> from the "src/test" directory to "src/userguide".
>
> Rationale: it's not really a test but actually a benchmark
> that's only useful through _looking_ at the output.
Why does the report itself belong in the user guide? Does it help
users make better decisions about how to use [math]? That is what
the User Guide is for - to help people find things and learn how to
use the software. If the performance tests help make decisions,
then fine; if not they should not be reproduced in the guide. Or
are you just suggesting we move the code there so it is easier to
execute?
Phil
>
> Any objection?
>
>
> Gilles
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
For additional commands, e-mail: dev-help@commons.apache.org