Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #39945 > unrolled thread

Do you feel bad because of the Python docs?

Back to article view | Back to comp.lang.python

Contents

  Do you feel bad because of the Python docs? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-02-26 12:54 +0000
    Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-27 00:20 +1100
      Re: Do you feel bad because of the Python docs? Roy Smith <roy@panix.com> - 2013-02-26 08:56 -0500
        Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-27 01:26 +1100
          Re: Do you feel bad because of the Python docs? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-02-26 15:26 +0000
        Re: Do you feel bad because of the Python docs? MRAB <python@mrabarnett.plus.com> - 2013-02-26 17:48 +0000
          Re: Do you feel bad because of the Python docs? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-02-27 03:02 +0000
    Re: Do you feel bad because of the Python docs? Zero Piraeus <schesis@gmail.com> - 2013-02-26 10:15 -0400
    Re: Do you feel bad because of the Python docs? Devin Jeanpierre <jeanpierreda@gmail.com> - 2013-02-26 09:15 -0500
    Re: Do you feel bad because of the Python docs? notbob <notbob@nothome.com> - 2013-02-26 16:19 +0000
      Re: Do you feel bad because of the Python docs? Andrew Berg <bahamutzero8825@gmail.com> - 2013-02-26 10:55 -0600
        Re: Do you feel bad because of the Python docs? notbob <notbob@nothome.com> - 2013-02-26 17:54 +0000
          Re: Do you feel bad because of the Python docs? Tim Chase <python.list@tim.thechases.com> - 2013-02-26 12:10 -0600
            Re: Do you feel bad because of the Python docs? notbob <notbob@nothome.com> - 2013-02-26 18:41 +0000
      Re: Do you feel bad because of the Python docs? nn <pruebauno@latinmail.com> - 2013-02-26 11:00 -0800
        Re: Do you feel bad because of the Python docs? emile <emile@fenx.com> - 2013-02-26 16:36 -0800
    Re: Do you feel bad because of the Python docs? "Adam W." <AWasilenko@gmail.com> - 2013-02-26 08:38 -0800
      Re: Do you feel bad because of the Python docs? Devin Jeanpierre <jeanpierreda@gmail.com> - 2013-02-26 13:52 -0500
      Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-02-26 20:48 -0500
        Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-26 19:13 -0800
          Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-02-27 15:25 -0800
            Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-27 18:05 -0800
              Re: Do you feel bad because of the Python docs? Roy Smith <roy@panix.com> - 2013-02-27 21:21 -0500
              Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-28 13:44 +1100
                Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-27 19:43 -0800
                  Re: Do you feel bad because of the Python docs? llanitedave <llanitedave@veawb.coop> - 2013-02-27 20:04 -0800
                  Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-02-27 20:21 -0800
              Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-02-27 20:18 -0800
                Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-27 20:53 -0800
                  Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-02-27 21:57 -0800
                    Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-28 17:31 +1100
                    Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-28 10:28 -0800
                      Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-03-01 07:41 +1100
                      Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-02-28 16:05 -0800
                        Re: Do you feel bad because of the Python docs? Jake Angulo <jake.angulo@gmail.com> - 2013-03-04 10:47 +1100
            Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-05 17:43 -0800
              Re: Do you feel bad because of the Python docs? Mark Lawrence <breamoreboy@yahoo.co.uk> - 2013-03-06 03:12 +0000
                Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-08 19:10 -0800
            Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-05 17:50 -0800
            Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-05 17:51 -0800
              Re: Do you feel bad because of the Python docs? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-03-06 03:38 +0000
                Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-08 19:31 -0800
                  Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-03-09 14:45 +1100
              Re: Do you feel bad because of the Python docs? rh <richard_hubbe11@lavabit.com> - 2013-03-06 11:48 -0800
              Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-03-06 18:50 -0500
                Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-03-06 16:47 -0800
                  Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-03-06 17:06 -0800
                    Re: Do you feel bad because of the Python docs? Chris Kaynor <ckaynor@zindagigames.com> - 2013-03-06 17:28 -0800
                    Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-03-06 17:31 -0800
                      Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-03-06 18:28 -0800
                        Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-03-06 18:57 -0800
                          Re: Do you feel bad because of the Python docs? alex23 <wuwei23@gmail.com> - 2013-03-06 19:12 -0800
                            Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-03-06 19:48 -0800
                      Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-03-07 13:16 +1100
                    Re: Do you feel bad because of the Python docs? "Michael Ross" <gmx@ross.cx> - 2013-03-07 03:04 +0100
                  Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-03-06 20:52 -0500
                    Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-03-06 18:41 -0800
                Re: Do you feel bad because of the Python docs? Bob Hanson <invalid@invalid.invalid> - 2013-03-08 20:12 -0800
                  Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-03-09 01:22 -0500
          Re: Do you feel bad because of the Python docs? Roy Smith <roy@panix.com> - 2013-02-27 20:26 -0500
    Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-02-26 13:43 -0500
      Re: Do you feel bad because of the Python docs? rurpy@yahoo.com - 2013-02-27 17:17 -0800
        Re: Do you feel bad because of the Python docs? Mark Lawrence <breamoreboy@yahoo.co.uk> - 2013-02-28 01:39 +0000
        Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-02-27 21:27 -0500
    Re: Do you feel bad because of the Python docs? Mitya Sirenef <msirenef@lightbird.net> - 2013-02-26 13:58 -0500
    Re: Do you feel bad because of the Python docs? rh <richard_hubbe11@lavabit.com> - 2013-02-26 12:18 -0800
    Re: Do you feel bad because of the Python docs? Rotwang <sg552@hotmail.co.uk> - 2013-02-26 21:26 +0000
      Re: Do you feel bad because of the Python docs? Jason Swails <jason.swails@gmail.com> - 2013-02-26 17:17 -0500
        Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-26 17:22 -0800
        Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-26 17:22 -0800
    Re: Do you feel bad because of the Python docs? Mark Janssen <dreamingforward@gmail.com> - 2013-02-26 17:15 -0800
    Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-27 12:31 +1100
    Re: Do you feel bad because of the Python docs? Terry Reedy <tjreedy@udel.edu> - 2013-02-26 21:00 -0500
    Re: Do you feel bad because of the Python docs? rh <richard_hubbe11@lavabit.com> - 2013-02-26 18:06 -0800
    Re: Do you feel bad because of the Python docs? Mitya Sirenef <msirenef@lightbird.net> - 2013-02-26 22:09 -0500
    Re: Do you feel bad because of the Python docs? Mitya Sirenef <msirenef@lightbird.net> - 2013-02-26 23:45 -0500
    Re: Do you feel bad because of the Python docs? Mark Lawrence <breamoreboy@yahoo.co.uk> - 2013-02-27 09:47 +0000
    Re: Do you feel bad because of the Python docs? Antoine Pitrou <solipsis@pitrou.net> - 2013-02-27 13:17 +0000
    Re: Do you feel bad because of the Python docs? Antoine Pitrou <solipsis@pitrou.net> - 2013-02-27 13:22 +0000
      Re: Do you feel bad because of the Python docs? Rick Johnson <rantingrickjohnson@gmail.com> - 2013-02-27 14:59 -0800
    Re: Do you feel bad because of the Python docs? Mitya Sirenef <msirenef@lightbird.net> - 2013-02-27 17:43 -0500
    Re: Do you feel bad because of the Python docs? rurpy@yahoo.com - 2013-02-27 15:20 -0800
      Re: Do you feel bad because of the Python docs? Steven D'Aprano <steve+comp.lang.python@pearwood.info> - 2013-02-28 01:05 +0000
        Re: Do you feel bad because of the Python docs? rurpy@yahoo.com - 2013-02-27 21:36 -0800
    Re: Do you feel bad because of the Python docs? llanitedave <llanitedave@veawb.coop> - 2013-02-27 18:26 -0800
    Re: Do you feel bad because of the Python docs? Jason Friedman <jsf80238@gmail.com> - 2013-02-27 21:59 -0700
    Re: Do you feel bad because of the Python docs? Chris Angelico <rosuav@gmail.com> - 2013-02-28 16:21 +1100
    Re: Do you feel bad because of the Python docs? << No! Tony the Tiger <tony@tiger.invalid> - 2013-03-03 16:28 -0600
    Re: Do you feel bad because of the Python docs? rh <richard_hubbe11@lavabit.com> - 2013-03-04 08:59 -0800

Page 5 of 5 — ← Prev page 1 2 3 4 [5]

#40076

On 02/27/2013 08:22 AM, Antoine Pitrou wrote:
> Mitya Sirenef <msirenef  <at> lightbird.net> writes:
 >> I think the issue with python documentation is that it ignores the 95/5
 >> rule: 95% of people who land on a module's page are only looking for 5%
 >> of its information.
 >
 > The 95/5 rule is generally a fallacy which ignores that the 5% which the
 > readers are expecting to learn about is not the same 5% from reader 
to reader.
 > (*)
 >
 > Which means that in the end you would really want a diversity of HOWTOs
 > targeted at different usages of the stdlib. But it is a lot of work to
 > write *and* maintain.
 >
 > (*) cf. http://www.joelonsoftware.com/items/2006/12/09.html
 >
 > Regards
 >
 > Antoine.
 >
 >

It would be absurd on my part to claim that they're precisely the same
5%. But then again, they don't have to be. Consider that some topics are
covered in the official tutorial while others are omitted -- the authors
of the tutorial were following the same rough 95/5 concept and the idea
that some readers will find stuff they don't need in the tutorial while
at the same time not finding some of what they DO need -- did not stop
them from writing the tutorial, nor does it mean the tutorial is not
useful. -m



-- 
Lark's Tongue Guide to Python: http://lightbird.net/larks/

[toc] | [prev] | [next] | [standalone]

#40079

On 02/26/2013 05:54 AM, Steven D'Aprano wrote:
> One week ago, "JoePie91" wrote a blog post challenging the Python 
> community and the state of Python documentation, titled:
> 
> "The Python documentation is bad, and you should feel bad".
> 
> http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
> and-you-should-feel-bad/
> 
> It is valuable to contrast and compare the PHP and Python docs:

tl;dr? tb

I haven't used PHP or its documentation so I can't compare it 
to Python's.  I have used Python's documentation and can say 
I agree with many of the criticisms made by JoePie91.

One of the problems with "fixing" the Python reference docs
(by which I mean primarily the Language and Library References)
it that there is no common agreement about what a "good"
reference should be.  In the Python development community
that controls the overall structure and contents of the
Python documentation, there seems to be strong minimalist
streak.  It often seems like the documentation is the 
product of a contest to find the minimum number of words to 
describe something and still be able to defend it as correct.

Any documentation must be written with a target audience in 
mind and IMO the audience for the Python reference docs should 
be programmers familiar with one or two procedural or OO 
languages at an intermediate level.  (Obviously different 
sections of documentation can modify this.  Later documentation
will assume knowledge of basic concepts like Python objects, 
argument passing and assignment semantics and so forth that
were presented earlier, and documentation for specialized 
problem domain modules, eg an SMTP module, would assume some
knowledge of email, smtp and networking.)

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.  I distinguish reference from tutorial material 
in that the former is optimized for looking up information
and presenting it concisely, the latter for presenting (quite 
possibly the same) information in a linear fashion with no 
forward references and presenting it verbosely and experientially.
I distinguish a language reference from a language standard 
in that the audience for the latter are language implementors
rather than users.  I would describe a reference document for 
those already competent with Python and as a big cheat-sheet.

A frequent failing of the Python docs is just plain poor
writing.  When explaining something, start with a description
of what the something is, does, etc, in a form understandable 
by the target audience.  Is there anyone who can understand
what the very useful collections.defaultdict does without
multiple rereadings?  According to its docs, it "returns a 
new dictionary-like object."  That is underspecified -- many 
things return dictionary-like objects.  It continues "it 
overrides one method and adds one writable instance variable." 
OK, but WTF does it *do*?!  It then goes on to describe its
use which one has to understand without an overarching context
and then reason backwards to eventually figure out that it is
a dict that provides for user-specified behavior when accessed 
with a key that doesn't exist [*1]

Important quality enablers are good tables of contents, 
indexes, glossaries, cross references and examples.

Examples should be used to illustrate a textual description
and never used as a substitute for textual descriptions.

Cross references are particularly important in tying together
related material that is found in disparate doc locations.  
For example, information on Python's "+" operator is found in:
 Lang: 2.5. Operators
 Lang: 3.3.7. Emulating numeric types
 Lang: 6.5. Unary arithmetic and bitwise operations
 Lang: 6.6. Binary arithmetic operations
 Lang: 6.15. Summary (mislabeled, actually operator precedence)
 Lib: 4.4. Numeric Types
 Lib: 4.6.1. Common Sequence Operations
 Lib: 10.3. operator
and probably other places I did not think to look.
The index is not much help in tying any of these together:
 "add"  -> Lib: 2.5
 "+"    -> Lib: 4.4
 "plus" -> Lang: 6.5
There are also more obscure uses that should be findable such
as in float hex strings (4.4.3. Additional Methods on Float)

Cross references to similar information can help cover for
failings in the index -- if you can find some similar function 
or concept, there is (or should be) a good chance of a cross-
reference to what you really wanted.

Good documentation will anticipate the questions a reader
will have and answer them.

----
Rebuttals to common responses to criticism of Python docs:

Python docs are already good
* Criticisms of Python's docs pop up on the Python 
 maillist and blogs with regularity.
* Many people confuse "usable", "i've learned to use
 despite", "look impressive", etc with "good".

Google / blogs / stackoverflow / reddit, etc can provide better
* Even were it true, it is an argument that Python
 doesn't need good documentation, rather than an argument
 that Python's docs are good.
* They don't provide answers for infrequent questions. 
* Answers can be conflicting, wrong, or out of date with
 no way to correct.
* Even today, not everyone has access to internet all the 
 time.

Try it in an interactive Python session
* This is useful practical advice but experiments do 
 not substitute for documentation because they tell you 
 only what Python version 3.3 on Redhat Linux 4.2 does 
 on a machine with 2GB of memory 3 days after the full
 moon. 
 Documentation is the ultimate authority for what it 
 is *supposed* to do.  

Read the source code
* Oh please!  The purpose of documentation is to alleviate
 the need to read source code.  
* Those most in need of documentation are those without
 the Python knowledge to read the source code.
* Some source code is very complex and difficult to understand
 even for experts.
* The behavior of source code is often obscured by details
 not directly related to the info being looked for: error
 handling, options for alternate behavior, performance
 optimizations etc..

Don't complain, submit doc fixes.
* The people with motivation to fix the docs are often not
 qualified to and the people qualified to have no motivation
 because they already know it.  (They may not even recognize
 there is a problem.)
* There is a group of core developers who define (by accepting
 or rejecting patches) the nature of the changes that can be
 made.  If the view of this group favors changes that continue
 the status-quo, significant improvements via this route are
 not possible.
* Small fixes can require orders of magnitude more effort to
 submit and defend than the fix took to write.

Tutorials are the place to explain basics.
* Tutorials are great for some people but not everyone.
* They are not optimized for looking up and answering specific
 questions.
* Their linear style builds on preceding info requiring
 start-to-end reading.
* Since finding info in them is harder, there is an expectation
 the reader will permanently commit the information to memory
 as encountered.  The best learning style for many is to
 memorize most frequently needed info by looking things up as
 needed.
* They often introduce programming or general programming
 language concepts already known to the reader from prior
 experience.
* They are often bloated with exercises/examples that are
 not needed by readers with a higher level of experience. 
* They require an unreasonable time/effort commitment for
 those without a preexisting commitment to using Python.
* They are an alternate format of, not a replacement for, 
 information that should be in reference manuals.

The high standards demanded are impossible
* There are other reference manuals that do achieve a high
 standard so it is not impossible, for example Beasley's 
 Python Essential Reference [*2].  The are also examples
 for other languages. 
* But, it may be impractical for the Python community
 to achieve such results due to various Python intra-
 community factors.

Python docs are excellent compared to most free software docs
* The "most free software docs" bar is too low to be a good
 metric.  Most such docs vary between "sucks" and "non-existent". 
 Please compare Python docs to best available docs (which is
 why comparison to commercial books like Beasley's Essential
 Reference is valid.)

----
[*1] I am not an advanced Python user nor a good technical
 writer so my defauldict description may well be poor.  That
 does not mean that a better description than currently exists 
 can't or shouldn't be provided.

[*2] I am not holding up Beazley's book as a gold standard;
 it has a number of its own problems.  But it does provide
 an example of reference material with better organization 
 and clarity than the python.org docs. 

[toc] | [prev] | [next] | [standalone]

#40088

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

[toc] | [prev] | [next] | [standalone]

#40110

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.

[toc] | [prev] | [next] | [standalone]

#40096

I just completed my first Python app for public consumption, and I was learning as I was coding.  I've played on the outskirts of the language for a few years, but until this project I'd never really immersed myself in it.  I ended up being confused a lot.  So, I DO have some relevant thoughts:

1.  The Python official documentation is not great, but it's not bad either.  Some of it seems outdated, some of it is a bit hard to parse, some of it assumes more background knowledge on the part of the reader than is justified.

Somebody mentioned the Django documentation.  I've looked at it a bit, and it's *very* nice.  I do think that the PSF could take some clues from its style and approach. 
But those are pretty minor gripes.  I've learned a lot from referencing the documentation, and its still my first go-to source when I'm stuck.

2.  The Python Community:  Jopie91 wrote "I will no doubt piss off quite a few people with this statement, but the community around Python is one of the most hostile and unhelpful communities around any programming-related topic that I have ever seen – and with that I am not just referring to #python on Freenode, but to communities with a dense population of Python developers in general. This point actually consists of several separate attitudes and issues."

There, I'd have to say he's very, very wrong.  When I have on occasion asked questions on this group I've never been flamed, and I've always had people give me thoughtful answers that obviously took some effort to compose.

My most recent question here concerned something that was thought to be a bug, but was due more to my own unfamiliarity with the material combined with what I'd suggest really was some ambiguity on the part of the documentation.  Nevertheless, even with the misunderstandings, my questions were treated respectfully, and that's all I ask.

[toc] | [prev] | [next] | [standalone]

#40107

> Python has a nice Tutorial for beginners. It is an integral part of the doc
> set. To ignore that (and the indexes) in discussing the usability of Python
> docs by beginners is to lie. (If beginners who actually read the tutorial
> have problems with particular paragraphs, improvements can be and have been
> made.)

I never thought about the quality of the Python docs until reading
these posts.  I started with Python by reading the tutorial and
browsing the module pages and have reached some level of competency.
I suppose the module pages could stand to have more examples, but as
Chris Angelico says this list should be considered part of the
documentation, in which case the documents plus this list effectively
give me any example I am wanting.  I am very grateful to those who
have given their time writing the existing documentation, answering
questions on this list, and of course writing the language!  Python
has allowed me to be more successful at my job than the other
languages I considered.

The lazy and workable approach is to read the module documentation,
make a reasonable effort, follow
http://www.catb.org/esr/faqs/smart-questions.html, and voilà.

[toc] | [prev] | [next] | [standalone]

#40108

On Thu, Feb 28, 2013 at 3:59 PM, Jason Friedman <jsf80238@gmail.com> wrote:
> The lazy and workable approach is to read the module documentation,
> make a reasonable effort, follow
> http://www.catb.org/esr/faqs/smart-questions.html, and voilà.

The Force is strong with this one.

If only others would follow this lazy approach...

ChrisA

[toc] | [prev] | [next] | [standalone]

#40425 — Re: Do you feel bad because of the Python docs? << No!

On Tue, 26 Feb 2013 12:54:56 +0000, Steven D'Aprano wrote:

<not much I was interested in commenting on>

 /Grrr
-- 
          ___                  ___
 (\_--_/)  | _ ._    _|_|_  _   |o _  _ ._
 ( 9  9 )  |(_)| |\/  |_| |(/_  ||(_|(/_|
 stripes are forever - as overripe ferrets

[toc] | [prev] | [next] | [standalone]

#40466

On Tue, 26 Feb 2013 18:06:21 -0800
rh <richard_hubbe11@lavabit.com> wrote:

> On 26 Feb 2013 12:54:56 GMT
> Steven D'Aprano <steve+comp.lang.python-iDnA/YwAAsAk
> +I/owrrOrA@public.gmane.org> wrote:
> 
> > One week ago, "JoePie91" wrote a blog post challenging the Python 
> > community and the state of Python documentation, titled:
> > 
> > "The Python documentation is bad, and you should feel bad".
> > 
> > http://joepie91.wordpress.com/2013/02/19/the-python-documentation-is-bad-
> > and-you-should-feel-bad/
> > 
> > It is valuable to contrast and compare the PHP and Python docs:
> > 
> > http://php.net/manual/en/index.php
> > http://www.python.org/doc/
> 
> FWIW,  I refer to the docs often. I keep a local copy and
> serve the pages up locally
> 
> 1. http://docs.python.org/2/archives/python-2.7.3-docs-html.tar.bz2
> 2. unroll
> 3. cd python-2.7.3-docs-html
> 4. python -c 'import SimpleHTTPServer as foo;foo.test()' 9292
> 5. point browser to 0:9292

I find that this works now to replace step #4:
python -m SimpleHTTPServer 9292

[toc] | [prev] | [standalone]

Page 5 of 5 — ← Prev page 1 2 3 4 [5]

Back to top | Article view | comp.lang.python

csiph-web