Do you feel bad because of the Python docs?

[Steven D'Aprano]

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