On Sun, Jan 13, 2013 at 8:28 PM, Phil Steitz <phil.ste...@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. Thomas
