[Zope3-dev] Re: Windows eggs

[Stephan Richter]

On Sunday 15 July 2007 12:45, Marius Gedminas wrote:
> I was talking about regular programmer-facing documentation and couldn't
> find a good word for it (tutorial?  programmer's guide).  The thing you
> read to learn about the package, not the thing you use to look up some
> details of some function.

Right, explanatory text.

> > That's a huge win coming from interfaces, in my opinion.
>
> I wish pydoc knew about zope interfaces...

Me too. At least APIDOC knows about them. However, with the component 
architecture I find all of those tools rather limiting, since they do not 
reveal anything about how components can be put together, like is this used 
as a utility or what adapters are available?

> > I never do this anymore. If I have a collection of utility functions, I
> > Still put them in a text file, because text files allow me to concentrate
> > on documentation.
>
> Perhaps I did not get my point clearly accross.  Python modules with
> doctests are useful for testing the various corner cases that you did
> not test in the corresponding .txt file.

I test all corner cases in the text file. I have learned that as long as you 
cannot explain something to someone else, you do not understand it yourself 
well enough. Writing documentation even for the corner cases ensures that I 
have motivation for the case and I can explain why I think this is the right 
solution.

Note that there are plenty of technical writing techniques to cover special 
cases. You can use footnotes, chapters, and appendices to talk about them. We 
are doing nothing new here; we just should not refuse to use well-established 
writing methods just because we are doing software engineering.

> If you put the tests for all your corner cases into the documentation,
> it quickly becomes unreadable.

I totally disagree. If it becomes unreadable, your writing skills are lacking.

I relate this to Phsyics, which makes what you are saying clearer: If I have 
to explain to you all the gory details of solving this problem, then the 
lecture/write-up becomes incomprehensible. In my experience only a bad 
educator would make such a statement. A good educator takes the time to break 
down the problem and explain everything about the problem. In our case, 
educator equals writer. Which brings me to my final point: When I am writing 
doctests I do not wear my programmer hat, but my educator/writer hat. I think 
very carefully about the use cases the reader might have in mind, 
expectations s/he might have when hearing a term, existing knowledge that I 
expect the reader to bring into the reading, etc.

> Right, but test_foo.py is never about documentation, it's about isolated
> unit tests.

But what is a unit test without documentation? In my opinion, it is a brittle 
test. Because documentation formalizes intend, while the test formalizes 
functionality. In the SchoolTool code (can't remember where) I have seen 
tests where the documentation deviated from the test code. Would the 
documentation not be there, the disacrepency would not be shown at all.

Writing a one liner is fine, but it will never be as thought out as if you 
were to write an explanatory text.

All this reminds me of another practice that I really dislike. Some people, 
when fixing a bug, will create a separate section at the end of document, 
often titled something like "Demonstration of Bug XXX". I think this is 
rather dubious, since people learning the API after the bug has been fixed 
were never aware of it in the first place and now wonder why the bug case is 
so special.

A bug fixer should find the documentation discussing the subject and insert 
text adn test in a way that the text keeps flowing. I know this is not easy; 
sometimes when I cannot find any good place, I create a footnote, which 
effectively is a non-flowing piece of text, but it is at least located at the 
right location.

Okay, I am done preaching. ;-)

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