[m-dev.] for review: quickcheck user guide

[Mark Anthony BROWN]

Hi,

Here's some general comments on the qcheck user guide.

	- The introduction should start by explaining what qcheck is,
	  and give a general overview of what the software is capable
	  of.  E.g.:
		- it's an automated testing tool
		- the user specifies properties, which qcheck randomly tests
		- user can control the distribution of tests in various ways

	- Some information about how the tests are run and how the outcome
	  is decided needs to be given earlier in the tutorial.  I think
	  it would be better to discuss the "property" type more, and it
	  should be done earlier in the tutorial.  This will make the
	  examples a lot easier to understand, IMHO.

	- The discussion about general and specific frequencies is a bit
	  difficult to follow.  The main problem is that it is not
	  immediately clear what their purpose is.  I think you need to give
	  an overview of what the user can do with these features.

	  In particular, it is not obvious enough what is meant by "specific".
	  Specific to what?  The answer becomes clearer (implicitly) later on
	  when general frequency is discussed, but I think it would be better
	  to explain it earlier.

	- In tute 4 (a.k.a. tute 1.4) you give a summary of how the property
	  that is returned by an invariant function is interpreted by qcheck.
	  You should do the same for generators at the end of tute 9.
	  That is, give a list of the steps taken by qcheck to determine
	  which generator is used in certain circumstances.

This concludes my first round of reviewing.  When you have addressed the
issues that have been raised, please post another diff.  It would also
be handy if you provide a URL pointing to the new version of the pages.
However, you should leave these pages unchanged while the review round is
taking place.  While I was reviewing the current set of pages they were
being modified, which made it a bit confusing -- it's more difficult to
review a moving target than one which is static.  You should be making the
suggested changes in your own workspace, rather than where the reviewer
is looking.

Cheers,
Mark.

--------------------------------------------------------------------------
mercury-developers mailing list
Post messages to:       mercury-developers at cs.mu.oz.au
Administrative Queries: owner-mercury-developers at cs.mu.oz.au
Subscriptions:          mercury-developers-request at cs.mu.oz.au
--------------------------------------------------------------------------