Pythondocs.info : collaborative Python documentation project

[Wildemar Wildenburger]

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

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]

Re: Pythondocs.info : collaborative Python documentation project

* nicolasfr@gmail .com (2006-09-16 18:40 +0100)

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

*chuckle* *manic laughter* *cough cough* X L - you really made my
day...

Thorsten

[Brad Allen]

Re: Pythondocs.info : collaborative Python documentation project

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]

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.
>
Regards,
>
Nicolas.
-----
http://www.pythondocs.info

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]

Re: Pythondocs.info : collaborative Python documentation project

On Sunday 17 September 2006 04:31, Brad Allen wrote:

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

[Brad Allen]

Re: Pythondocs.info : collaborative Python documentation project


Rakotomandimby (R12y) wrote:

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

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]

Re: Pythondocs.info : collaborative Python documentation project

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

them and adding examples.

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.

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

Re: Pythondocs.info : collaborative Python documentation project

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

majorfunction.e xample()
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]

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

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

Regards,
>
Nicolas.
-----
http://www.pythondocs.info

[Kay Schluehr]

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.
>
Regards,
>
Nicolas.
-----
http://www.pythondocs.info

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]

Re: Pythondocs.info : collaborative Python documentation project


Kay Schluehr wrote:

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]

Re: Pythondocs.info : collaborative Python documentation project

On Sun, 17 Sep 2006 18:10:51 +0200,
Daniel Nogradi <nogradi@gmail. comwrote:

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]

Re: Pythondocs.info : collaborative Python documentation project


A.M. Kuchling wrote:

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]

Re: Pythondocs.info : collaborative Python documentation project

On 9/17/06, A.M. Kuchling <amk@amk.cawrot e:

On Sun, 17 Sep 2006 18:10:51 +0200,
Daniel Nogradi <nogradi@gmail. comwrote:

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

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]

Re: Pythondocs.info : collaborative Python documentation project


Brad Allen wrote:

A.M. Kuchling wrote:

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.

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_na me>.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:

>>svn.show_proj ects()
>>proj = svn.open_projec t(project_name)
>>proj.checkin( module_name)
>>proj.checkin_ all()
>>svn.checkout( another_project )

etc.