Do you feel bad because of the Python docs?
rurpy at yahoo.com
rurpy at yahoo.com
Thu Feb 28 06:36:29 CET 2013
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.
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
>> 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.
More information about the Python-list