On Fri, Dec 9, 2011 at 6:41 PM, "Martin v. Löwis" <mar...@v.loewis.de> wrote: >> a) The stdlib documentation should help users to choose the right tool >> right from the start. Instead of using the totally misleading wording >> that it uses now, it should be honest about the performance >> characteristics of MiniDOM and should actively suggest that those who >> don't know what to choose (or even *that* they can choose) should not >> use MiniDOM in the first place. > > I disagree. The right approach is not to document performance problems, > but to fix them.
When we offer a better way to do something that new users are want to do, we generally redirect them to the more recent alternative. I believe the redirection from the getopt module to the argparse module strikes the right tone for that kind of thing: http://docs.python.org/library/getopt For the various XML libraries, a message along the lines of "Note: The <whatever> module is a <yada, yada, DOM based, whatever>. If all you are trying to do is read and write XML files, consider using the xml.etree.ElementTree module instead". I'd also be +1 on adjusting the order of the XML pages in the main index such that xml.etree.ElementTree appeared before xml.parser.expat and all the others slid down one entry. These are simple changes that don't harm current users of the modules in the least, while being up front and very helpful for beginners. Again, I think argparse vs getopt is a good comparison: argparse appears first in the main index, and there's a redirection from getopt to argparse that says "if you don't have a specific reason to be using getopt, you probably want argparse instead". -- Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com