Pythondocs.info : collaborative Python documentation project

[nicolasfr]

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.

 

[Wildemar Wildenburger]

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

 

[Steve Holden]

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

 

[nicolasfr]

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.

 

[Christoph Haas]

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

 

[Rakotomandimby (R12y)]

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.

 

[Robert Hicks]

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]

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

 

[Leif K-Brooks]

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.

 

[nicolasfr]

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!

 

[Daniel Nogradi]

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.

 

[Wildemar Wildenburger]

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

 

[Eric_Dexter]

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

 

[Rakotomandimby (R12y)]

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)]

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

ASPN (activestate) is a good place for examples...

 

[Wildemar Wildenburger]

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

 

[Thorsten Kampe]

* (e-mail address removed) (2006-09-16 18:40 +0100)

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

 

[Brad Allen]

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.

 

[Paddy]

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.

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.

 

[Christoph Haas]

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