Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Pythondocs.info : collaborative Python documentation project

Reply
Thread Tools

Pythondocs.info : collaborative Python documentation project

 
 
nicolasfr@gmail.com
Guest
Posts: n/a
 
      09-16-2006
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

 
Reply With Quote
 
 
 
 
Wildemar Wildenburger
Guest
Posts: n/a
 
      09-16-2006
http://www.velocityreviews.com/forums/(E-Mail Removed) 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
 
Reply With Quote
 
 
 
 
Steve Holden
Guest
Posts: n/a
 
      09-16-2006
(E-Mail Removed) 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

 
Reply With Quote
 
nicolasfr@gmail.com
Guest
Posts: n/a
 
      09-16-2006

Wildemar Wildenburger wrote:
> (E-Mail Removed) 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/pyt...ay/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.

 
Reply With Quote
 
Christoph Haas
Guest
Posts: n/a
 
      09-16-2006
On Saturday 16 September 2006 19:16, (E-Mail Removed) 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
 
Reply With Quote
 
Rakotomandimby (R12y)
Guest
Posts: n/a
 
      09-16-2006
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/pyt...ay/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.

 
Reply With Quote
 
Robert Hicks
Guest
Posts: n/a
 
      09-16-2006

(E-Mail Removed) wrote:
> Wildemar Wildenburger wrote:
> > (E-Mail Removed) 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/pyt...ay/280634.html
>\


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

Robert

 
Reply With Quote
 
Robert Hicks
Guest
Posts: n/a
 
      09-16-2006

Christoph Haas wrote:
> On Saturday 16 September 2006 19:16, (E-Mail Removed) 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

 
Reply With Quote
 
Leif K-Brooks
Guest
Posts: n/a
 
      09-16-2006
(E-Mail Removed) 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.
 
Reply With Quote
 
nicolasfr@gmail.com
Guest
Posts: n/a
 
      09-16-2006

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!

 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
ANN: consensus 0.1.1 - Collaborative filtering library for Python Brian Beck Python 0 03-19-2006 03:07 AM
collaborative web navigation tool in python (z9) Andre Rodrigues Python 0 03-16-2006 01:56 AM
collaborative working Jonathan Crawford ASP .Net 2 09-30-2005 08:58 AM
Python documentation: How about structured documentation? Looking for comments/suggestions Kenneth McDonald Python 2 05-06-2004 04:11 AM
Principles of documentation (was: Python Documentation Blows!) Cameron Laird Python 1 04-03-2004 06:54 PM



Advertisments