PHP Documentation

[Guyon Morée]

hi, I've been working with PHP lately and what I found is that the docs are
awesome, as is the python are python docs btw. but one thing that I really
like about theirs is the doc-commenting system it has.

any user can comment on any page in the docs. this results in a lot of
clarifications and examples for the subjects at hand.

is it an idea to implement this in the python docs?
i believe it's a good idea what are your thoughts?

 

[Peter Hansen]

hi, I've been working with PHP lately and what I found is that the docs are
awesome, as is the python are python docs btw. but one thing that I really
like about theirs is the doc-commenting system it has.

any user can comment on any page in the docs. this results in a lot of
clarifications and examples for the subjects at hand.

is it an idea to implement this in the python docs?
i believe it's a good idea what are your thoughts?

This comes up every month or three in this newsgroup and I think
I can summarize the comments of others by saying two things:

1) Thinking it's a good idea isn't enough if you want it: somebody
has to implement it. It's been suggested before, so at this
point the next step is for someone who likes the idea enough
to just do it.

2) Many people think that the noise created by lots of user
comments would far outweigh the value of the good comments
that might be hidden somewhere within.

-Peter

 

[Alex Martelli]

2) Many people think that the noise created by lots of user
comments would far outweigh the value of the good comments
that might be hidden somewhere within.

As long as it's possible to request a view or download of the docs
without the comments, I don't see how this could be a problem -- if you
want to see the docs with comments you can, if not, you're no worse off
than today. With the kind of threshold-setting and ratings for various
commenters that (e.g.) slashdot uses, you could also set up your
preferences to see _some_ of the comments but not all.

In theory any wiki page could be "defaced" by one nasty minded vandal,
in practice most wikis seem to work decently well -- maybe people react
positively to being trusted. If comments (and posters thereof,
eventually) can be rated, existing comments edited or removed only by
authorized personnel, etc, etc, I suspect it would work. No doubt the
needed infrastructure already exists on the widely appreciated PHP doc
pages, it remains to be seen whether we're humble enough to just copy it
wholesale or if the prospect of running PHP code in a key supporting
role for Python is just too embarassing;-).


Alex

 

[Larry Bates]

Zope has such a system in place for their docs. You can just ask
that the comments be hidden and they disappear. It does appear to
provide a way to make comments, add examples clarification that
"may" get included in the next version of the docs.

Larry Bates
Syscon, Inc.

 

[A.M. Kuchling]

1) Thinking it's a good idea isn't enough if you want it: somebody
has to implement it. It's been suggested before, so at this
point the next step is for someone who likes the idea enough
to just do it.

Someone started doing it manually -- see
http://www.python.org/moin/PythonLibraryReference .

--amk

 

[Tor Iver Wilhelmsen [TeamB]]

any user can comment on any page in the docs. this results in a lot of
clarifications and examples for the subjects at hand.

is it an idea to implement this in the python docs?

Zope already does this as well.

 

[Peter Hansen]

Someone started doing it manually -- see
http://www.python.org/moin/PythonLibraryReference .

I guess it might help to publicize it, such as via your posting. ;-)

Since Lloyd did that on May 11 it appears nobody has modified
any of the PythonLibraryReference pages.

More precisely, nobody has appended any comments per the original
instructions, though it's possible someone modified the text in
violation of those instructions.

Wikis can be useful for maintaining documentation, but so far
I've seen it succeed only in very limited instances, and in this
case without top level support (e.g. recognition by the official
doc maintainers that this is now the master copy) I really doubt
it will get far. Feel free, anyone, to prove me wrong.

-Peter

 

[A.M. Kuchling]

Wikis can be useful for maintaining documentation, but so far
I've seen it succeed only in very limited instances, and in this
case without top level support (e.g. recognition by the official
doc maintainers that this is now the master copy) I really doubt
it will get far. Feel free, anyone, to prove me wrong.

I can't see the Wiki version ever becoming the master copy; Wiki markup is
much less detailed than the LaTeX macros, e.g. in the Wiki you can only put
things in ``code-style``, but in the LaTeX you have \member{} and
\constant{} and \keyword{} and many other different shades of meaning.

It probably wouldn't be difficult to take the HTML rendering of the docs and
automatically import them into an empty Wiki instance that could then be
updated. Will anyone volunteer to do this?

--amk

 

[Albert Hofkamp]

Nice discussion here. I am also attracted to the PHP doc system, for the
moment mainly for internal documentation.


Ok, let me try
[ For clarity:
I am not an editor of anything, except my own documentation
]

Roughly, there are 4 groups of users:

- People that do not read docs.

- People that read docs, and do not comment on it.

- People that read docs, and write useless comments (useless w.r.t. an
editor, for example 'I don't understand this section')

- People that read docs and write useful comments.

The first two groups are not interesting (maybe the first group is, to
some extent but that is a different discussion).

The latter group are people that an editor wants to spend time on.
Typically (I imagine, I am not an editor), you get feedback about
specific points in the docs, or (even better) complete patches which can
be integrated.

The third group is for an editor mainly waste of time. Without any more
details, you cannot figure out what is wrong, so fixing is difficult at
best.


The current system where everybody can submit reports and patches to the
docs using the sourceforge project stops most people of the third group
(at least, I hope it does for the sake of our editors), and very little
of the 4th group (writing down the specific points or writing a patch is
much more effort than submitting it as a bug to the sourceforge
project).
[ at least, it didn't stop me submitting changes ]

By lowering the treshold for submitting changes, you will get more
response, but imho mostly from the 3rd group, not the 4th group. I.e you
create more work, but not better patches/feedback.

I can't see the Wiki version ever becoming the master copy; Wiki markup is
much less detailed than the LaTeX macros, e.g. in the Wiki you can only put
things in ``code-style``, but in the LaTeX you have \member{} and
\constant{} and \keyword{} and many other different shades of meaning.

There are some other considerations as well. I rely on the docs asif it
is the voice of our beloved BDFL, ie I assume that they tell the one and
only truth.
If you allow anyone to edit anything, this may go wrong in a very
serious way.

Also, there are (unwritten?) agreements that anything undocumented may
change or disappear at any time, and anything documented changes very
slowly if at all. That means that somebody in charge should give the
green light before new parts get documented.
I believe that such agreements are good; by using documented calls, I
get some limited form of guarantuee that code I write will not cease
working suddenly.

In other words, I am not convinced that we'd want public write access to
the documents.


Having said that, a workable solution can be constructed quite easily
(isn't Open Source wonderful?).

Anyone can copy the doc source, put them at his own server, and serve
the pages to browsers all over the world and collect comments either in
PHP style or in Wiki style. Then, the owner of the server can browse
the collected comments, makes them edible for our source documentation,
and submit the patches to the bug tracker. I am sure that the doc
editors are happy to integrate any such patches to the existing source
documents.
If this works well, you (the server owner doing the editing work)
a) attract more users than the main documentation.
Since you get modifications, you can publish them before the official
documents. That should make your site more attractive than the official
one.
b) get enough credit of the editors that at some point you may get write
access to the source documents (ie you can then eliminate the bug
report step),
c) may convince our editors that having an interactive doc modification
system is indeed an improvement.
and possible some other advantages as well.

It probably wouldn't be difficult to take the HTML rendering of the docs and
automatically import them into an empty Wiki instance that could then be
updated. Will anyone volunteer to do this?

One aspect I am interested in, is how do you know what is updated? Is
there some underlying version control system, or does the wiki keep
track of modifications?
(I know what wiki is, but I haven't played with any yet).

Albert