PHP Documentation

[Albert Hofkamp]

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

On Mon, 30 Aug 2004 13:02:14 -0500, A.M. Kuchling <amk at amk.ca> wrote:
> On Mon, 30 Aug 2004 12:48:13 -0400, 
>> 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.

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
-- 
Unlike popular belief, the .doc format is not an open publically available format.