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. -- http://mail.python.org/mailman/listinfo/python-list
