Re: PHP style Annotated Manual

The wiki stuff has been ported to servlets, if that is of any interest.

--DC--
----- Original Message -----
From: "Sam & Lisa Snow" <2snows@mailandnews.com>
To: <pgsql-general@postgresql.org>
Cc: "'Richard'" <poboxcanada@yahoo.com>; "'Dave Cramer'"
<Dave@micro-automation.net>; "'Michael Ansley'"
<Michael.Ansley@intec-telecom-systems.com>
Sent: Saturday, February 17, 2001 5:34 PM
Subject: [GENERAL] 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@Opus1.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@php.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@vinylbaby.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
>
>
>
>
>