Pythondocs.info : collaborative Python documentation project

Discussion in 'Python' started by nicolasfr@gmail.com, Sep 16, 2006.

  1. Guest

    Hi,

    I am a bit disapointed with the current Python online documentation. I
    have read many messages of people complaining about the documentation,
    it's lack of examples and the use of complicated sentences that you
    need to read 10 times before understanding what it means.

    That's why I have started a collaborative project to make a user
    contributed Python documentation. The wiki is online here:
    http://www.pythondocs.info

    This is a fresh new website, so there's not much on it, but I hope to
    make it grow quickly. Help and contributions are welcome; Please
    register and start posting your own documentation on it.

    Regards,

    Nicolas.
    -----
    http://www.pythondocs.info
     
    , Sep 16, 2006
    #1
    1. Advertising

  2. wrote:
    > I have read many messages of people complaining about the documentation,
    > it's lack of examples and the use of complicated sentences that you
    > need to read 10 times before understanding what it means.
    >

    Where have you read that?

    wildemar
     
    Wildemar Wildenburger, Sep 16, 2006
    #2
    1. Advertising

  3. Steve Holden Guest

    wrote:
    > Hi,
    >
    > I am a bit disapointed with the current Python online documentation. I
    > have read many messages of people complaining about the documentation,
    > it's lack of examples and the use of complicated sentences that you
    > need to read 10 times before understanding what it means.
    >
    > That's why I have started a collaborative project to make a user
    > contributed Python documentation. The wiki is online here:
    > http://www.pythondocs.info
    >
    > This is a fresh new website, so there's not much on it, but I hope to
    > make it grow quickly. Help and contributions are welcome; Please
    > register and start posting your own documentation on it.
    >

    While I am all in favor of improving Python's documentation I am not
    sure that fragmenting it in this way is a good idea. Couldn't you
    instead devote your efforts to improving the docs at docs.python.org? It
    is, after all, an open source project ...

    regards
    Steve
    --
    Steve Holden +44 150 684 7255 +1 800 494 3119
    Holden Web LLC/Ltd http://www.holdenweb.com
    Skype: holdenweb http://holdenweb.blogspot.com
    Recent Ramblings http://del.icio.us/steve.holden
     
    Steve Holden, Sep 16, 2006
    #3
  4. Guest

    Wildemar Wildenburger wrote:
    > wrote:
    > > I have read many messages of people complaining about the documentation,
    > > it's lack of examples and the use of complicated sentences that you
    > > need to read 10 times before understanding what it means.
    > >

    > Where have you read that?
    >
    > wildemar


    I don't mean to start a flame war about this but here are some
    reference of people, who like me, don't like the current python doc:
    http://xahlee.org/UnixResource_dir/writ/python_doc.html
    http://mail.python.org/pipermail/python-list/2005-May/280634.html
    ....
    You really can find dozens of such discussions on the net.

    I think the PHP documentation is a really good one in comparison.

    Nicolas.
     
    , Sep 16, 2006
    #4
  5. On Saturday 16 September 2006 19:16, wrote:
    > I am a bit disapointed with the current Python online documentation. I
    > have read many messages of people complaining about the documentation,
    > it's lack of examples and the use of complicated sentences that you
    > need to read 10 times before understanding what it means.
    >
    > That's why I have started a collaborative project to make a user
    > contributed Python documentation. The wiki is online here:
    > http://www.pythondocs.info
    >
    > This is a fresh new website, so there's not much on it, but I hope to
    > make it grow quickly. Help and contributions are welcome; Please
    > register and start posting your own documentation on it.


    I like your enthusiasm but it appears that what you plan is similar to the
    Python Quick Reference at http://rgruet.free.fr/

    I second that the Python documentation is lacking. There is no software
    that is adequately documented anyway. Show me a man page of a Perl module
    and it takes me minutes to use it. The same in Python often means Google
    to find some examples on how to use a module. Many parts of the standard
    library are badly documented IMHO. There is often no way to know how to
    use a certain module without looking at its source. But why don't you and
    I rather provide patches to the current documentation rather than writing
    yet another incomplete resource. IMHO python.org should be completed. And
    at least you motivated me to look for ways to contribute to python.org. :)

    Cheers
    Christoph
     
    Christoph Haas, Sep 16, 2006
    #5
  6. On Sat, 16 Sep 2006 10:40:43 -0700, nicolasfr wrote:
    >>> I have read many messages of people complaining about the documentation,
    >>> it's lack of examples and the use of complicated sentences that you
    >>> need to read 10 times before understanding what it means.

    >> Where have you read that?

    > http://xahlee.org/UnixResource_dir/writ/python_doc.html
    > http://mail.python.org/pipermail/python-list/2005-May/280634.html
    > I think the PHP documentation is a really good one in comparison.


    What you should have done first is to suggest to contribute to the
    official Python doc.
    Then, if you encounter too much dumbs (and only in that case) you could
    fork docs.python.org and do your own project.
    That's the way free software works.
     
    Rakotomandimby (R12y), Sep 16, 2006
    #6
  7. Robert Hicks Guest

    wrote:
    > Wildemar Wildenburger wrote:
    > > wrote:
    > > > I have read many messages of people complaining about the documentation,
    > > > it's lack of examples and the use of complicated sentences that you
    > > > need to read 10 times before understanding what it means.
    > > >

    > > Where have you read that?
    > >
    > > wildemar

    >
    > I don't mean to start a flame war about this but here are some
    > reference of people, who like me, don't like the current python doc:
    > http://xahlee.org/UnixResource_dir/writ/python_doc.html
    > http://mail.python.org/pipermail/python-list/2005-May/280634.html
    >\


    Please don't use Xah Lee as an example...please.

    Robert
     
    Robert Hicks, Sep 16, 2006
    #7
  8. Robert Hicks Guest

    Christoph Haas wrote:
    > On Saturday 16 September 2006 19:16, wrote:

    <snip>
    >
    > I second that the Python documentation is lacking. There is no software
    > that is adequately documented anyway. Show me a man page of a Perl module
    > and it takes me minutes to use it.


    I would say that Perl module documentation is really good. Most of them
    have plenty examples on how to use the module itself.

    That said...the Python docs are open source. Just start going through
    them and adding examples. It shouldn't be too hard and will benefit
    everyone who use them.

    Robert
     
    Robert Hicks, Sep 16, 2006
    #8
  9. wrote:
    > I am a bit disapointed with the current Python online documentation. I
    > have read many messages of people complaining about the documentation,
    > it's lack of examples and the use of complicated sentences that you
    > need to read 10 times before understanding what it means.
    >
    > That's why I have started a collaborative project to make a user
    > contributed Python documentation. The wiki is online here:
    > http://www.pythondocs.info


    I agree that Python's docs could use improvement, and I love the idea of
    using a Wiki for the purpose. But maybe MediaWiki would be a better
    choice of software? Dokuwiki's syntax looks foreign and a little bit
    intimidating to me, but Wikipedia has made pretty much everyone familiar
    with MediaWiki's syntax. Less syntax to learn lowers the cost of entry,
    which should lead to more contributors.
     
    Leif K-Brooks, Sep 16, 2006
    #9
  10. Guest

    Rakotomandimby (R12y) wrote:
    > What you should have done first is to suggest to contribute to the
    > official Python doc.


    I wrote an email a few months ago to the Python docs support email
    address to offer my help but never got any answer.

    > Then, if you encounter too much dumbs (and only in that case) you could
    > fork docs.python.org and do your own project.
    > That's the way free software works.


    Everytime I am lookink at how to do this or that in Python I write it
    down somewhere on my computer. (For ex. Threading. After reading the
    official documentation I was a bit perplex. Hopefully I found an
    article an managed to implement threads with only like 20 lines of code
    in my script. That should have been in the docs first, not in an
    article elsewhere... Same problem for handling gzipped files. I wanted
    to know if the file I opened was a gzip archive or not. Not a clue in
    the docs...) I have just decided to share all this knowledge this with
    other. Community will decide if this wiki is of any interest. If not it
    will just remain my personnal notebook for Python tips...

    Anyway Python rocks, that's the important point!
     
    , Sep 16, 2006
    #10
  11. > Everytime I am lookink at how to do this or that in Python I write it
    > down somewhere on my computer. (For ex. Threading. After reading the
    > official documentation I was a bit perplex. Hopefully I found an
    > article an managed to implement threads with only like 20 lines of code
    > in my script. That should have been in the docs first, not in an
    > article elsewhere... Same problem for handling gzipped files. I wanted
    > to know if the file I opened was a gzip archive or not. Not a clue in
    > the docs...) I have just decided to share all this knowledge this with
    > other. Community will decide if this wiki is of any interest. If not it
    > will just remain my personnal notebook for Python tips...
    >
    > Anyway Python rocks, that's the important point!
    >


    Then how about running your site on python and not php?

    Just a thought.
     
    Daniel Nogradi, Sep 16, 2006
    #11
  12. wrote:
    > Rakotomandimby (R12y) wrote:
    >> What you should have done first is to suggest to contribute to the
    >> official Python doc.

    >
    > I wrote an email a few months ago to the Python docs support email
    > address to offer my help but never got any answer.
    >

    What did that email say?
    - "Your docs suck!"? (useless)
    - "Your docs aren't the most useful. May I offer to help?" (better, but
    somewhat thin. And if the answer had just been "Yes." You'd be no wiser.)
    - "Hey, I found this article explaining XY. I made a
    tutorial/how-to/documentation-chapter, and here it is. Hope you can use
    it." (fantastic/preferred)

    http://www.python.org/dev/doc/ has info on how to participate.


    > Everytime I am lookink at how to do this or that in Python I write it
    > down somewhere on my computer. (For ex. Threading. After reading the
    > official documentation I was a bit perplex. Hopefully I found an
    > article an managed to implement threads with only like 20 lines of code
    > in my script. That should have been in the docs first, not in an
    > article elsewhere... Same problem for handling gzipped files. I wanted
    > to know if the file I opened was a gzip archive or not. Not a clue in
    > the docs...) I have just decided to share all this knowledge this with
    > other. Community will decide if this wiki is of any interest. If not it
    > will just remain my personnal notebook for Python tips...


    Let me stress that contributing to the *official* docs is a lot more
    rewarding and (I think) sensible. I can't stop you and I appreciate your
    enthusiasm. You might however consider helping fix the dam than build
    one where no water water runs.

    wildemar
     
    Wildemar Wildenburger, Sep 16, 2006
    #12
  13. Guest

    I would like to see more than one source.. Not that the documentation
    is good or bad it is just that different people may come up with
    different ways to explain the same thing and that is good in my view.
    I would like to see the re module and the string module with as many
    examples as humanly possible to overexplain it for me. (I am currently
    downloading a hole directory of re module stuff to try to overcome it)

    http://www.dexrow.com




    Leif K-Brooks wrote:
    > wrote:
    > > I am a bit disapointed with the current Python online documentation. I
    > > have read many messages of people complaining about the documentation,
    > > it's lack of examples and the use of complicated sentences that you
    > > need to read 10 times before understanding what it means.
    > >
    > > That's why I have started a collaborative project to make a user
    > > contributed Python documentation. The wiki is online here:
    > > http://www.pythondocs.info

    >
    > I agree that Python's docs could use improvement, and I love the idea of
    > using a Wiki for the purpose. But maybe MediaWiki would be a better
    > choice of software? Dokuwiki's syntax looks foreign and a little bit
    > intimidating to me, but Wikipedia has made pretty much everyone familiar
    > with MediaWiki's syntax. Less syntax to learn lowers the cost of entry,
    > which should lead to more contributors.
     
    , Sep 16, 2006
    #13
  14. On Sat, 16 Sep 2006 22:43:41 +0200, Daniel Nogradi wrote:
    > Then how about running your site on python and not php?


    PHP has "better" documentation... ;-)
    More seriously, I can provide a CPS hosting to nicolasfr if he wants.
     
    Rakotomandimby (R12y), Sep 16, 2006
    #14
  15. On Sat, 16 Sep 2006 12:30:56 -0700, Robert Hicks wrote:

    > That said...the Python docs are open source. Just start going through
    > them and adding examples.


    ASPN (activestate) is a good place for examples...
     
    Rakotomandimby (R12y), Sep 16, 2006
    #15
  16. wrote:
    > Hi,
    >
    > I am a bit disapointed with the current Python online documentation. I
    > have read many messages of people complaining about the documentation,
    > it's lack of examples and the use of complicated sentences that you
    > need to read 10 times before understanding what it means.
    >
    > That's why I have started a collaborative project to make a user
    > contributed Python documentation. The wiki is online here:
    > http://www.pythondocs.info


    And what's so wrong about
    http://wiki.python.org/moin/ ?

    I'm really not trying to put you down, I just feel that the closer the
    documentation is to the official website the more people will read it
    (or am I being too naive here?).

    wildemar
     
    Wildemar Wildenburger, Sep 16, 2006
    #16
  17. * (2006-09-16 18:40 +0100)
    > Wildemar Wildenburger wrote:
    >> wrote:
    >>> I have read many messages of people complaining about the documentation,
    >>> it's lack of examples and the use of complicated sentences that you
    >>> need to read 10 times before understanding what it means.
    >> >

    >> Where have you read that?
    >>
    >> wildemar

    >
    > I don't mean to start a flame war about this but here are some
    > reference of people, who like me, don't like the current python doc:
    > http://xahlee.org/UnixResource_dir/writ/python_doc.html


    *chuckle* *manic laughter* *cough cough* X L - you really made my
    day...

    Thorsten
     
    Thorsten Kampe, Sep 17, 2006
    #17
  18. Brad Allen Guest

    Here is an idea for improving Python official documentation:

    Provide a tab-based interface for each entry, with the overview/summary
    at the top-level, with a row of tabs underneath:
    1. Official documentation, with commentary posted at the bottom
    (ala Django documentation)
    2. Examples wiki
    3. Source code browser with a folding/docstring mode
    4. Bugs/To-Do

    Of course, building this would take a lot of work, and I'm not offering
    to build it myself...I just find that something like this is what I've
    been longing for.
     
    Brad Allen, Sep 17, 2006
    #18
  19. Paddy Guest

    wrote:
    > Hi,
    >
    > I am a bit disapointed with the current Python online documentation. I
    > have read many messages of people complaining about the documentation,
    > it's lack of examples and the use of complicated sentences that you
    > need to read 10 times before understanding what it means.
    >
    > That's why I have started a collaborative project to make a user
    > contributed Python documentation. The wiki is online here:
    > http://www.pythondocs.info
    >
    > This is a fresh new website, so there's not much on it, but I hope to
    > make it grow quickly. Help and contributions are welcome; Please
    > register and start posting your own documentation on it.
    >
    > Regards,
    >
    > Nicolas.
    > -----
    > http://www.pythondocs.info


    I wonder about what is going wrong here. On the one hand we have
    http://www.awaretek.com/tutorials.html with its "more than 300
    tutorials", and on the other we have maybe too many people disgruntled
    with the main Python documentation.

    It seems people want to make better Python documentation and are
    willing to put in the effort.
    Maybe there is something broken in the process for contributing to the
    official documentation?

    Personally, I thought it was OK back in 199.... but I did program in
    several other languages, including scripting languages, before Python.

    - Paddy.
     
    Paddy, Sep 17, 2006
    #19
  20. On Sunday 17 September 2006 04:31, Brad Allen wrote:
    > Here is an idea for improving Python official documentation:
    >
    > Provide a tab-based interface for each entry, with the overview/summary
    > at the top-level, with a row of tabs underneath:
    > 1. Official documentation, with commentary posted at the bottom
    > (ala Django documentation)
    > 2. Examples wiki
    > 3. Source code browser with a folding/docstring mode
    > 4. Bugs/To-Do


    I like your idea. The MySQL documentation site just came up to my mind.
    Users can write comments to articles there. And the documentation team can
    pick them up and include them in the official documentation. What annoys
    me most about the Python documentation is that it may be technically
    complete but a human being will never figure out how to solve the puzzle
    of 50 class methods without getting a proper example. It's like showing
    some non computer scientists a syntax diagram to get them started with
    something.

    For today I plan to check out the SVN repository containing the official
    Python documentation and see how well I can contribute. But since many
    people are probably good Python programmers but less good in maintaining
    complex documentation structures (especially in LaTeX) it might help to
    allow more direct contributions. Ubuntu's Launchpad for example contains a
    component where anyone can help translate docstrings for Debian/Ubuntu
    packages. No more knowledge needed.

    At least it doesn't appeal to me if Python's documentation team says "just
    open up a bug report on sourceforge - we will deal with the rest". Perhaps
    this is a decent approach considering the quality of contributions. I
    can't tell.

    Christoph
     
    Christoph Haas, Sep 17, 2006
    #20
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. moondusterone
    Replies:
    4
    Views:
    398
    moondusterone
    Oct 12, 2005
  2. Robert Hicks

    PYTHONDOCS on OSX

    Robert Hicks, Nov 28, 2005, in forum: Python
    Replies:
    3
    Views:
    316
    Dan Lowe
    Nov 28, 2005
  3. Chris Smith

    PYTHONDOCS

    Chris Smith, Dec 31, 2005, in forum: Python
    Replies:
    13
    Views:
    764
    Florian Diesch
    Jan 9, 2006
  4. Andre Rodrigues
    Replies:
    0
    Views:
    250
    Andre Rodrigues
    Mar 16, 2006
  5. Brian Beck
    Replies:
    0
    Views:
    583
    Brian Beck
    Mar 19, 2006
Loading...

Share This Page