Do you feel bad because of the Python docs?
Steven D'Aprano
steve+comp.lang.python at pearwood.info
Wed Feb 27 20:05:17 EST 2013
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
More information about the Python-list
mailing list