[Zope3-dev] Re: Windows eggs

[Stephan Richter]

On Saturday 14 July 2007 04:05, Marius Gedminas wrote:
> Absolutely!  Trying to reach two unrelated goals (comprehensive tests +
> human-friendly documentation) with one file is just too hard, if not
> impossible.

While it cannot be done in one file, I think it can be done in one style of 
writing. I have found that modules do not just split up in logical units, but 
also in usage. I tend to write one text file per module. Thus, naturally, 
some will read more like usage instructions and others like API 
documentation.

Another good method is to write a simple example first explaining the most 
common usage and dive into the special cases later on. Of course, this style 
of writing is common in introductory science/engineering books and is nothing 
new.

For functional tests I use a somewhat different approach, writing one text 
file per user and task, and name it something like admin-createsite.txt.

BTW, I think the Storm tutorial is okay, but not exceptionally good. At the 
beginning it lacks introduction of what storm is and what its goals are. 
While a specific example is used in the tutorial all the writing is done 
generically talking about programming concepts. This is like talking about 
the gravitational force in physics and use a flying canon ball as an example. 
Something that attracts me is the choice of small sections/chapters.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training