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