Pythondocs.info : collaborative Python documentation project

[Brad Allen]

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

Yes, but that requires a separate search and depends on an external
organization. Wouldn't it be great if relevant examples were a single
click away from official documentation on any given module? Examples
could either come in via a wiki approach, or maybe in some cases from
the doctests, which would be nice to have alongside handy access to the
source code.

 

[Daniel Nogradi]

That said...the Python docs are open source. Just start going through

Yes, but that requires a separate search and depends on an external
organization. Wouldn't it be great if relevant examples were a single
click away from official documentation on any given module? Examples
could either come in via a wiki approach, or maybe in some cases from
the doctests, which would be nice to have alongside handy access to the
source code.

Since the activestate site is already an established repository for
code snippets and examples I don't think it would be a good idea to
start a new one. What would be very useful though is more visible
links on the python.org site to the activestate repository where
appropriate. I'm not sure the pyhon.org people would want to promote
activestate though, nevertheless it would be a great help to many.

 

[ernesto.adorio]

Somehow all of the above discussions did not mention having examples or
demos "built-in" for the language itself:

majorfunction.example()
demo("package") or package.demo()
search engine in local html documentation
apropos()

The statistical software R is bettter in this respect if you really
wanted such kind of help.

-Ernie Adorio

 

[Fuzzyman]

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.

There is *already* an online collaborative project for the Python
tutorial and reference :

http://pytut.infogami.com/
http://pyfaq.infogami.com/
http://pyref.infogami.com/

Please contribute to these.

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

 

[Kay Schluehr]

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.

Personally, I never found the Python docs particular bad. It is
rewarding to write good documentation because documentation has
different aspects i.e. introductory/tutorial, exhaustive/manual and
design documentation aspects. Not to mention cookbook recipes.

I also observe that the discussion about Python docs is very tool
centered and my question to all the people who believe to improve the
Python docs by converting old tuturials into Wikis is that: what are
the precise requirements? Will an internet connection soon be necessary
to know how the sys module works? Are there any thoughts about
integrating 3rd party module/package documentation with the docs of the
stdlib / tutorial / language ref etc.so that they finally find their
logical place in the system ? Are there any intentions to create an
informational PEP regarding documentation in any forseeable future or
shall documentation projects continue to start in the wild?

So far I've not seen a documentation project ( besides the "official"
one of course ) that provided qualified criticism and didn't suffer
from a second system syndrome.

 

[Brad Allen]

Personally, I never found the Python docs particular bad. It is
rewarding to write good documentation because documentation has
different aspects i.e. introductory/tutorial, exhaustive/manual and
design documentation aspects. Not to mention cookbook recipes.

I also observe that the discussion about Python docs is very tool
centered and my question to all the people who believe to improve the
Python docs by converting old tuturials into Wikis is that: what are
the precise requirements? Will an internet connection soon be necessary
to know how the sys module works?

+1 that downloadability is an important requirement; wiki does not
preclude this
-1 on wiki as the only approach; wiki could be an adjunct to officially
managed docs

Are there any thoughts about
integrating 3rd party module/package documentation with the docs of the
stdlib / tutorial / language ref etc.so that they finally find their
logical place in the system ?

This could become a natural progression once a full-featured
documentation system is in place.

Are there any intentions to create an
informational PEP regarding documentation in any forseeable future or
shall documentation projects continue to start in the wild?

Sounds like a great idea. We should probably do more brainstorming and
discussion about the particulars before someone spends a lot of time
writing a PEP. We could create a separate topic in this forum, titled
something like 'Ideas for a new PEP on Python.org documentation
structure, UI, and processes'.

 

[A.M. Kuchling]

start a new one. What would be very useful though is more visible
links on the python.org site to the activestate repository where
appropriate. I'm not sure the pyhon.org people would want to promote
activestate though, nevertheless it would be a great help to many.

There's no reason not to link to ActiveState... but are there RSS
feeds or some similar mechanism to get all the recipes for a
particular module?

Fredrik Lundh also proposed a way to publish examples that get linked
from the documentation <http://effbot.org/zone/idea-seealso.htm>, and
there's some code in the Python sandbox for incorporating links
(sandbox/seealso).

However, this code isn't used at the moment because I have no idea
what to do about version controlling the links. Do we just use the
current links whenever the HTML is generated? Make a copy of the list
and commit them into SVN, so the links cease to be updated but are
consistent for a given version's docs? It would be nice to figure out
what to do.

--amk

 

[Brad Allen]

However, this code isn't used at the moment because I have no idea
what to do about version controlling the links. Do we just use the
current links whenever the HTML is generated? Make a copy of the list
and commit them into SVN, so the links cease to be updated but are
consistent for a given version's docs? It would be nice to figure out
what to do.

That sounds like another good reason to handle the examples at
python.org, but it argues against a wiki approach for examples. Maybe
the examples should be part of the same SVN repository; if they are
implemented as doctests they can be validated before each new release.
On the other hand, that probably only works for very simple examples;
I've seen some extensive examples at in the Cookbook that might not fit
well into a doctest.

There could a separate tab for "Links" alongside tabs for
documentation, svn source, doctests, discussion, bugs/requests, wiki.
The links tab might have a disclaimer to the effect of "Your Mileage
May Vary", and each link might have a date posted next to it. The
links might not all be examples; they could point to alternative tools,
related resources, more discussion -- whatever the community comes up
with. Eventually, someone would have to prune; the dates would help
with that. Also, if folks could rate the links, the best ones might
float to the top.

 

[Calvin Spealman]

There's no reason not to link to ActiveState... but are there RSS
feeds or some similar mechanism to get all the recipes for a
particular module?

Fredrik Lundh also proposed a way to publish examples that get linked
from the documentation <http://effbot.org/zone/idea-seealso.htm>, and
there's some code in the Python sandbox for incorporating links
(sandbox/seealso).

However, this code isn't used at the moment because I have no idea
what to do about version controlling the links. Do we just use the
current links whenever the HTML is generated? Make a copy of the list
and commit them into SVN, so the links cease to be updated but are
consistent for a given version's docs? It would be nice to figure out
what to do.

--amk

I think that, clearly, a combination of community and automation to
gather the best information from around the tubes is a good thing to
be explored further. However, without careful editing and eventual
integration into the official documentation, the information will just
stagnate under the rug.

Beyond just getting more information into the documentation, which
already covers everything if you know where to look, we need to
seriously take a look at how newcomers are thinking about the problems
they have and where they expect to find the answers. Perhaps some
rearranging of the documentation is in order, or some cross-references
to be added. These aspiring pythoners are asking "How do I do X?" and
there is no clear path to many of their answers without knowing the
answer yourself. That is the problem, more than any lack of examples
or clarity in the text.

How can we solve this? We need a two fold approach to improving the
documentation. We need to increase community support of the official
documentation, perhaps with forums/wikis attached to different parts
of the documentation for the dropping of examples, links, and
suggestions, along with discussion on how to further improve them. Add
a form (built into the wiki?) right there with the docs where people
can submit additions, corrections, expansions, and other changes to
request.

 

[Kay Schluehr]

That sounds like another good reason to handle the examples at
python.org, but it argues against a wiki approach for examples. Maybe
the examples should be part of the same SVN repository; if they are
implemented as doctests they can be validated before each new release.
On the other hand, that probably only works for very simple examples;
I've seen some extensive examples at in the Cookbook that might not fit
well into a doctest.

doctest is not the only way to present examples in code. The other one
is simply a link to the lib/test directory and the approriate
test_<module_name>.py module. Reading testcases is often the only
source I have when I want to understand how something works ( exercise:
try to create a code object from scratch using the new module and the
desciption provided in the docs ). I find Cookbook recipes a little
over the top for basic use pattern. They are usually not that well
factored that they present a single idea precisely.

Since we are at it: what about two additional directories within the
Python system namely "site-docs" and "site-test" for all kinds of
docs/tests of 3rd party modules/packages? Installing docs using
distutils might automatically update a single HTML site that contains
references to the package docs ( de-installing will cause another
update ).

Python24+-docs
+-site-docs
+-lib
+- test
+- site-test

or alternatively:

Python24+-lib
+-site-packages
+- site-docs
+- site-test

Executing all testcases of the stdlib already uses reflection over the
modules provided in the directory. Same basic mechanism could be
applied to site-test.

Note that once such an architecture is fixed there is no reason (
besides bandwidth of course ) not to use svn to manage user projects
within site-space completely. I would go even further and suggest to
implement some svn management functions within the Python console such
as:
etc.

 

[=?ISO-8859-1?Q?Michael_Str=F6der?=]

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

Frankly I'm tired of these yet-another-wiki announcements!
Who is supposed to fill them with content?

If you have improvements to the official docs put them into Python's SF
tracker:
http://sourceforge.net/tracker/?func=add&group_id=5470&atid=305470

Ciao, Michael.

 

[Bruno Desthuilliers]

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

Xah Lee is a well-known crank.

 

[Bruno Desthuilliers]

PHP has "better" documentation... ;-)
More seriously, I can provide a CPS hosting to nicolasfr if he wants.

Alert ! Unusable undocumented monstruosity ahead...

 

[Laurent Pointal]

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.

I agree in some ways, Python docs could have better organization (more links
between related things).

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.

Here is another URL of such a project, i bookmarked some times:
http://www.simisen.com/jmg/cpd/
And there is nothing beyond this URL, like many of such projects.

AFAIR there is a starting of Wiki documentation - like PHP docs, one page
per function, contributors comments & Co, from one main Python developers
(dont remember who start this neither what is the URL).

In all case, dont setup another new system, use
http://wiki.python.org/moin/, at least your work will not be lost.

A+

Laurent.

 

[Laurent Pointal]

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.

You're realy nor the first one, see
http://mail.python.org/pipermail/python-list/2004-May/219580.html
(and following thread)

Other (never achieved) projects... http://www.pythondocs.org/

Even Skip Montanaro python-glossary site seem to not have been continued...
http://mail.python.org/pipermail/python-list/2004-May/219682.html