On Mon, 4 Dec 2000, Lalo Martins wrote:
In the first section, remove "where does it come from" if the section involves the history of unit testing. I'd say the history lesson is out of scope. ;)
I would add a section in the beginning "Why do you want to use it".
The first section is the advocacy section; it will begin with "if you already do unit tests, you may want to skip this section". I'm not sure if the history lesson is out of scope, but "Why do you want to use it" is probably better.
Hmm... actually in that case you may want to axe both "why" and the history.
What does "refactor mercilessly!" mean?
I'll explain that one of the benefits of unit testing extensively is that you can modify your code without fear (you'll know when it breaks). This section is more advocacy than technical.
Ah, ok I like it. I wonder if "refactor" is the right word; it's very specific and it sounds like any kind of changing can be done.
Next section...
"Importing ZUnit" requires a whole section? I suggest axing it.
Hmm. Yes.
I would add an "example" section before moving into fitting it into Zope...
No, you can't do a lot without interfacing with Zope. I'd add an example *after* interfacing with Zope. Or both, perhaps. Maybe one example in the end of each subsection, so we don't need any subsection titled "example".
Oh, I was thinking of just a simple non-zope unit test to get the flavor, but now that I think about it that's out of scope. Yes, the example after would be better.
What are "Fixtures"?
A method where you make many tests in a single TestCase class. You setup a situation (the "fixture") in a method named "setup", then you do the tests, then you clean up in a method named "teardown". In the HiperDom tests, for example, I use a Fixture to do most of the tests, because I initialize the Template object in setup.
Ah yes, I just went and RTFM.
What is the "persistence problem"? If it is a bug that should be fixed in Zope then it probably shouldn't go in the documentation, if it is something the reader shouldn't do, then it should probably go into "interfacing with the Zope environment". A wart doesn't justify adding a new section just to add a sub-section to document it. ;)
I don't consider this a bug in either Zope or ZUnit, it's just an "issue".
<snip>
I allocated a subsection for this because just explaining the problem is already somewhat convoluted, as you see above ;-) in a printed book, I'd make it a sidebar or something, but...
Hmm. I guess my concern was because it was the only subsection of 'Fixtures'. Do fixtures need a more topical breakdown or are they simple enough to sum up in one section? Maybe we can think of some 'fixture use cases'. -Michel