PHP style Annotated Manual

I did a small bit of research on the PHP style of annotated manual. From
their documentation mailing list archives I was able to find out where to
get the source and some other discussion about it.

As long as the comments were moderated and rolled into the main manual
periodically, I think the system is great.

More thoughts? Any takers? Their system is based on MySQL, so it would take
a small porting effort. ;-)

Sam

===================

Follow the instructions on http://cvs.php.net to check out "phpweb"
instead of "php3", and you'll have the source for the enire website.

- Stig

======================

List: phpdoc
Subject: Re: [PHP-DOC] Dealing with the PHP manual annotations (was Re:
From: Ron Chmara <ron(at)Opus1(dot)COM>
Date: 2000-07-28 4:06:07
[Download message RAW]

A mini-summary of one exchange, first:

> > > The developers have expressed doubts about giving out CVS accounts.
> > I agree with them on this; handing them out left and right would make me
a
> > bit nervous, too.
> > > Alternately, the annotation system could be modified, but this would
take
> > > some time.
> > The annotations are stored a MySQL table. Perhaps the easiest approach
might
> > just be to add some sort of "editor reviewed" column to the database and
> > creating a separate page that would display unreviewed notes so that a
> > designated annotation editor (or group) could easily keep on top of new
> > notes.
> > > > I think a quick trip through the php-general archives
> > > > and the FAQ/KB listings would turn up some knowledgeable candidates
who
> > > > could be trusted for this sort of thing.
> > > I would guess that making a letter that invites people to help out on
this
> > > project would be the best way to do this?
> > What do you think about working with the doc team to establish either an
> > editor or review group and then sending out a message encouraging people
to
> > submit dubious annotations for review? Kind of like what is currently
being
> > done with the bugs database where the QA team is helping filter out easy
> > reports to save developer time.

A few thoughts....

Scaled annotation permissions, mailing requesting management, review group,
db column changes, a review page?

It's starting to sound a bit excessive for implementation of what is pretty
much a simple issue (cleaning up the annotations, which are db records).

How about:
1. Annotations themselves have feedback, at the bottom of the annotation
list.
This is either per section, per page, or even simpler, *an email addy
aliasing
to the annnotated manual doc folks*. This builds the communication channel,
simply an effciently, and increases user feedback. (Let the users of the
docs
handle the crawl as well)

First implementation is adding a single line to the annotation loop, of the
form:
<?php
echo "mailto:manualtenders(at)php(dot)net";
?>

Or whomever that mail alias should point to.

(Someone might want to fix the "http://www.php.net/manual/about-notes.php"
URL
while they're at it, too...)

It can go into a group IMAP box, a mailing list for debate,
whatever,*later*.
It may be split into whatever groups commitees, scaled permissions,
hierarchial \
ownership trees, etc. But email is simple enough to do _now_. If you want
to get \
fancy, you can put a mailto on each notation, so you can pick up the record
id in the \
loop in stick it in the subject.

The point of splitting the smaller tasks out is to get smaller, faster,
progress,
and a follow up review commitee is just asking for poilitical bureacracy to
get
in the way of, well, deleting messages, leaving others and deciding what to
send
upstream for actual manual edits.

2."We don't need no steenking CVS access". It's a web db. There's already an
interface for message building. Adding an update/delete page is equally
simple.

Worried about concurrency? Use the read or move of an IMAP box to indicate
that somebody has "checked out" the problem. The edits aren't 4 day debug
sessions,
they're add/delete/email-to-the-main-doc-team (if there is, indeed, a manual
error. Shouldn't take more than 3-5 minutes for each annotation.

The annotation folks don't have to be C coders, or navigate the perms or
manage
concurrency... they have to be able to handle:
a) email in from users, and out to main doc team
b) a web page or two.
c) Maybe a password (via htaccess) to get to the proper editing page.

The entire purpose of an annotated doc-tender would be to scrape off the
useless stuff, leave the good stuff, and pass requested manual edits
upstream
to the people who have CVS doc access, or into this list, or whatever (but
keep it simple)

Count me in, if'n ya'd like the help. First page I'd go after is the
less-than-helpful slow motion flamewar on:
http://www.php.net/manual/function.substr.php....

----Snippet:
> brian(at)vinylbaby(dot)com
> 19-Dec-1999 07:55
> I am sorry I started this. I was trying to point out an error and now this
page is \
> a mess. I hope someone will clean this garbage up.
----

-Ronabop