473,696 Members | 2,075 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

Pythondocs.info : collaborative Python documentation project

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 '06 #1
34 2917
ni*******@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
Sep 16 '06 #2
ni*******@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

Sep 16 '06 #3

Wildemar Wildenburger wrote:
ni*******@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/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.

Sep 16 '06 #4
On Saturday 16 September 2006 19:16, ni*******@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
Sep 16 '06 #5

ni*******@gmail .com wrote:
Wildemar Wildenburger wrote:
ni*******@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/pyt...ay/280634.html
\
Please don't use Xah Lee as an example...pleas e.

Robert

Sep 16 '06 #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/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.

Sep 16 '06 #7

Christoph Haas wrote:
On Saturday 16 September 2006 19:16, ni*******@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

Sep 16 '06 #8
ni*******@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.
Sep 16 '06 #9

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 '06 #10

This thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

3
1435
by: Robert Hicks | last post by:
How do I set this variable in my .bash_profile? I have the html docs in /usr/local/PythonDocs. Thanks for any help... Robert
13
2447
by: J. D. Leach | last post by:
OK, I'm stupid. I have been unable to discern (even Googled) a way to set the PYTHONDOCS variable to point to where the HTML files are. What to do? I need to know the process and where theses variables are stored. -- J. D. Leach Columbus, Indiana USA Linux/Open Source Computer using: Mandrakelinux release 10.2 (Limited Edition 2005) for i586 kernel 2.6.11-6mdk
0
8661
marktang
by: marktang | last post by:
ONU (Optical Network Unit) is one of the key components for providing high-speed Internet services. Its primary function is to act as an endpoint device located at the user's premises. However, people are often confused as to whether an ONU can Work As a Router. In this blog post, we’ll explore What is ONU, What Is Router, ONU & Router’s main usage, and What is the difference between ONU and Router. Let’s take a closer look ! Part I. Meaning of...
0
8595
by: Hystou | last post by:
Most computers default to English, but sometimes we require a different language, especially when relocating. Forgot to request a specific language before your computer shipped? No problem! You can effortlessly switch the default language on Windows 10 without reinstalling. I'll walk you through it. First, let's disable language synchronization. With a Microsoft account, language settings sync across devices. To prevent any complications,...
1
6512
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 1 May 2024 starting at 18:00 UK time (6PM UTC+1) and finishing by 19:30 (7.30PM). In this session, we are pleased to welcome a new presenter, Adolph Dupré who will be discussing some powerful techniques for using class modules. He will explain when you may want to use classes instead of User Defined Types (UDT). For example, to manage the data in unbound forms. Adolph will...
0
5855
by: conductexam | last post by:
I have .net C# application in which I am extracting data from word file and save it in database particularly. To store word all data as it is I am converting the whole word file firstly in HTML and then checking html paragraph one by one. At the time of converting from word file to html my equations which are in the word document file was convert into image. Globals.ThisAddIn.Application.ActiveDocument.Select();...
0
4353
by: TSSRALBI | last post by:
Hello I'm a network technician in training and I need your help. I am currently learning how to create and manage the different types of VPNs and I have a question about LAN-to-LAN VPNs. The last exercise I practiced was to create a LAN-to-LAN VPN between two Pfsense firewalls, by using IPSEC protocols. I succeeded, with both firewalls in the same network. But I'm wondering if it's possible to do the same thing, with 2 Pfsense firewalls...
0
4608
by: adsilva | last post by:
A Windows Forms form does not have the event Unload, like VB6. What one acts like?
1
3030
by: 6302768590 | last post by:
Hai team i want code for transfer the data from one system to another through IP address by using C# our system has to for every 5mins then we have to update the data what the data is updated we have to send another system
2
2313
muto222
by: muto222 | last post by:
How can i add a mobile payment intergratation into php mysql website.
3
1989
bsmnconsultancy
by: bsmnconsultancy | last post by:
In today's digital era, a well-designed website is crucial for businesses looking to succeed. Whether you're a small business owner or a large corporation in Toronto, having a strong online presence can significantly impact your brand's success. BSMN Consultancy, a leader in Website Development in Toronto offers valuable insights into creating effective websites that not only look great but also perform exceptionally well. In this comprehensive...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.