[Thomas Wouters] > ... > I think what's missing is a library *tutorial*. How would that differ from the effbot guide (to the std library)? The Python (language) Tutorial can be pretty small, because the Python language is pretty small. But the libraries are massive, and growing, and are increasingly in the hands of people with no Unix experience, or even programming experience. So I suppose "tutorial" can mean many things. > The reference is exactly that, a reference, In part. In other parts (a good example is the profile docs) it's a lot of everything; in others it's so much "a reference" you can't figure out what it's saying unless you study the code (the pre-2.1 "random" docs sure come to mind). It's no more consistent in content level than anything else with umpteen authors. > and if we expand the reference we'll end up cursing it ourself, > should we ever need it. If the people who wanted "just a reference" were happy, I don't think David Beazley would have found an audience for his "Python Essential Reference". I can't argue about this, though, because nobody will ever agree. Guido doesn't want leisurely docs in the Reference Manual, nor does he like leisurely docs in docstrings. OTOH, those are what average and sub-average programmers *need*, and I write docs for them first, sneaking in examples when possible that I hope even experts will find pleasure in pondering. A good compromise by my lights-- and perhaps because I only care about the HTML docs, where "size" isn't apparent or a problem for navigation --would be to follow a terse but accurate reference with as many subsections as felt needed, with examples and rationale and tutorial material (has anyone ever figured how to use rexec or bastion from the docs? heh). But since nobody will agree with that either, I stick everything into docstrings and leave it to Fred to throw away the most useful parts for the "real docs" <wink>. > ... > I remember when I'd finished the Python tutorial and wondered where to > go next. I tried reading the library reference, but it was boring and > most of it not interesting (since it isn't built up to go from > seful/common -> rare, but just a list of all modules ordered by > service'.) Excellent point! I had the same question when I first learned Python, but at that time the libraries were maybe 10% of what's there now. I *still* didn't know where to go next. But I was pretty sure I didn't need the SGI multimedia libraries that occupied half the docs <wink>. > ... > I'll write the library tutorial once I finish the 'from-foo-import-* > considered harmful' chapter ;-) Hmm. Feel free to finish the listcomp PEP too <wink>.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4