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 _______________________________________________ Zope3-dev mailing list Zope3email@example.com Unsub: http://mail.zope.org/mailman/options/zope3-dev/archive%40mail-archive.com