opinion: comp lang docs style

[Steven D'Aprano]

On Tue, 04 Jan 2011 15:17:37 -0800, rurpy at yahoo.com wrote:

>> If one wants to critique the 'Python Docs', especially as regards to
>> usefulness to beginners, one must start with the Tutorial; and if one
>> wants to use if statements as an example, one must start with the
>> above.
> 
> No.  The language reference (LR) and standard library reference (SLR)
> must stand on their own merits.  It is nice to have a good tutorial for
> those who like that style of learning.  But it should be possible for a
> programmer with a basic understanding of computers and some other
> programming languages to understand how to program in python without
> referring to tutorials, explanatory websites, commercially published
> books, the source code, etc.

No it shouldn't. That's what the tutorial is for. The language reference 
and standard library reference are there to be reference manuals, not to 
teach beginners Python.

In any case, your assumption that any one documentation work should stand 
on its own merits is nonsense -- *nothing* stands alone. Everything 
builds on something else. Technical documentation is no different: it 
*must* assume some level of knowledge of its readers -- should it be 
aimed at Python experts, or average Python coders, or beginners, or 
beginners to programming, or at the very least is it allowed to assume 
that the reader already knows how to read?

You can't satisfy all of these groups with one document, because their 
needs are different and in conflict. This is why you have different 
documentation -- tutorials and reference manuals and literate source code 
and help text are all aimed at different audiences. Expecting one 
document to be useful for all readers' needs is like expecting one data 
type to be useful for all programming tasks.

Reasonable people might disagree on what a particular documentation work 
should target, and the best way to target it, but not on the need for 
different documentation for different targets.


-- 
Steven