Pythondocs.info : collaborative Python documentation project

[nicolasfr@gmail.com]

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

[Wildemar Wildenburger]

Re: Pythondocs.info : collaborative Python documentation project

nicolasfr@gmail .com 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

[Steve Holden]

Re: Pythondocs.info : collaborative Python documentation project

nicolasfr@gmail .com 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

[nicolasfr@gmail.com]

Re: Pythondocs.info : collaborative Python documentation project


Wildemar Wildenburger wrote:

nicolasfr@gmail .com 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.

[Christoph Haas]

Re: Pythondocs.info : collaborative Python documentation project

On Saturday 16 September 2006 19:16, nicolasfr@gmail .com 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

[Robert Hicks]

Re: Pythondocs.info : collaborative Python documentation project


nicolasfr@gmail .com wrote:

Wildemar Wildenburger wrote:

nicolasfr@gmail .com 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...pleas e.

Robert

[Rakotomandimby (R12y)]

Re: Pythondocs.info : collaborative Python documentation project

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.

[Robert Hicks]

Re: Pythondocs.info : collaborative Python documentation project


Christoph Haas wrote:

On Saturday 16 September 2006 19:16, nicolasfr@gmail .com 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

[Leif K-Brooks]

Re: Pythondocs.info : collaborative Python documentation project

nicolasfr@gmail .com 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.

[nicolasfr@gmail.com]

Re: Pythondocs.info : collaborative Python documentation project


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!

[Daniel Nogradi]

Re: Pythondocs.info : collaborative Python documentation project

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]

Re: Pythondocs.info : collaborative Python documentation project

nicolasfr@gmail .com 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

[Eric_Dexter@msn.com]

Re: Pythondocs.info : collaborative Python documentation project

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:

nicolasfr@gmail .com 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.

[Rakotomandimby (R12y)]

Re: Pythondocs.info : collaborative Python documentation project

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

Re: Pythondocs.info : collaborative Python documentation project

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...