On Wed, 27 Feb 2013 15:20:04 -0800, rurpy wrote: > As JoePie91 pointed out, reference material should describe its subject > matter completely and accurately. Once documentation has archived that > minimum bar of viability, its quality is determined by how effectively > it transfers that information to the reader.
Those priorities are backwards. Badly written reference materials that are ineffective at transferring information is potentially useless, no matter how complete and accurate, and there's often not much you can do to make it better written other than throwing it away and starting again. But well-written reference material that is incomplete can be incrementally added to, eventually making it complete. If anyone thinks that being complete is more important than being readable, let me point out that the Python source code is a 100% complete and accurate reference to the behaviour of Python. So we're done, yes? No of course not. [...] > Documentation is the ultimate authority for what it is *supposed* to do. Incorrect. If that were true, then there could never be a documentation bug. Documentation can be buggy, just as software can be buggy. If function f() is documented as doing X, but actually does Y, which one is correct? In general there is no way to tell. In practice, the ultimate authority is the consensus (if any!) of the people who write the software. -- Steven -- http://mail.python.org/mailman/listinfo/python-list
