Do you feel bad because of the Python docs?

[rurpy at yahoo.com]

On 02/27/2013 06:05 PM, Steven D'Aprano wrote:
> 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.

Why assume "useless"?  The claim is that much of the 
current Python documentation is badly written but it 
is hardly useless.  Is it even possible to be "complete 
and accurate" and totally "useless" at the same time?

> But well-written reference material that is incomplete can be 
> incrementally added to, eventually making it complete.

And badly written documentation can be incrementally rewritten 
so I don't see your point.  If you going to start with the 
premise of docs so badly written they are *totally* "useless"
then start with an equally extreme incompleteness premise: 
there is no documentation at all (including source code if 
you want to consider that, "documentation"). 

> 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. 

It may be a complete and accurate if poorly readable 
reference for those who already know Python and C well
(and Java and C#/.net if you want to cover Python generally)
but the presumed target audience of the documentation does 
not necessarily know them.

And since you're claiming that readable is more important 
than complete and accurate, ask yourself which *you* would 
prefer if you could have only one: readable but incomplete
and inaccurate docs or the poorly readable but complete and 
accurate source code?

> So we're done, yes?

How so?  You have source code that is not useful for the 
intended audience of the documentation and no documentation.

> No of course not.

Right.

Perhaps a better way to look at it than I (or you) stated 
is to consider accuracy and completeness very important 
qualities of reference documentation, as is of course the 
writing quality.

> [...]
>> 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.

Correct documentation is the ultimate authority for what 
it is supposed to do.  In context, that was in contrast
to the oft-recommended technique of seeing what the software
does without reference to the documentation.  I take your 
point that when behavior and documentation disagree, it 
may not be immediately clear which is at fault but without 
reference to the documentation you will never even 
notice the discrepancy.