Re: [PEAR-QA] Package Abstracts

> This is a follow up on the "Documentation" discussion (and is probably
> in the wrong list, but since the discussion started here...)
>
> After manning the booth at our LinuxWorld stand and spending a good
> amount of time hanging around the booth at IPC2k4, I would like to
> propose that we create a simple format of the "mini-documentation" of
> EACH package.
>
> This documentation would not be comprehensive, but would be well written
> and provide an overview of what each package does. A good example is
> Perl's documentation which requires the following 5 sections:
>
> Name
> Abstract
> Synopsis
> Description
> Notes and Bugs
>
> I would propose that this documentation be maintained along with the
> packages, and updated to be included and installed in the docs/ folder
> with each release.

I think this should be part of the wiki. Each package will have its own
wiki area. Those requisites could be use for the base template.

> This is a fairly big job, but I think that the effort will be well worth
> the trouble, and will give PEAR a much more user-friendly face to the
> world (and put an end to the "PEAR is poorly documented" mantra we hear
> so often).

Indeed.

Arnaud.

On Tue, 2004-11-16 at 20:48, Arnaud Limbourg wrote: 
>
> I think this should be part of the wiki. Each package will have its own
> wiki area. Those requisites could be use for the base template.

I agree with Arnaud.
 
>
> Indeed.

This is a fairly big job yes, which I will most likely take upon my
self, since I've had this wiki idea stuck in my head since I and Arnaud
were looking at some apps together to being able to orginize LiveUser
much better, and we came upon http://projects.edgewall.com/trac/ which
is a great piece of software, has few drawbacks, but surly the basic
idea is great, and I'm pretty sure that when Arnaud mentioned wiki he
had something very similar as my ideas :)
Maybe I even can poke Arnaud to help with this ? (*pokes arnaud*)
Of course like said before, this is a huuuuge task, so it won't be ready
anytime soon, and hasn't been started as of now, more thought has to be
put into it, and what the wiki should be capable of and etc. i.e.
planing.

Any ideas for this people ? :)
Every idea will be considered so don't be shy! ;)

Regards
Helgi

On Nov 16, 2004, at 3:47 PM, Helgi =DEormar wrote:

> Of course like said before, this is a huuuuge task, so it won't be=20
> ready
> anytime soon, and hasn't been started as of now, more thought has to =
be
> put into it, and what the wiki should be capable of and etc. i.e.
> planing.
>
> Any ideas for this people ? :)
> Every idea will be considered so don't be shy! ;)

I have volunteered in the past, and will continue to do so on a=20
standing basis, to set up a YaWiki <http://yawiki.com> installation for=20=

pear.php.net.  It's all PEAR all the time, except for using Savant=20
<http://phpsavant.com> as its template system and Yawp=20
<http://phpyawp.com> as its foundation, so I hope that's not a=20
deal-breaker.  I did some work with Tobias Schlitt to get it up on a=20
test machine, but there have been some problems with that box.

As regards a YaWiki installation, my own opinion is that each PEAR=20
package would get its own area.  That results in a lot of areas, which=20=

means the default theme would not be useful; as such, it would need a=20
modified theme for displaying all the various areas.  Not hard in a=20
technical sense, but perhaps non-trivial from an organization and=20
display perspective.  Authentication would be nice, but not required,=20
if only so we can know who is doing what with documentation.

So again:  this is me volunteering to get a YaWiki installation going=20
on pear.php.net.


--=20

Paul M. Jones

Savant: the simple alternative to Smarty for PHP.
http://phpsavant.com/

DB_Table: build RDBMS tables and XHTML forms in one PHP class.
http://wiki.ciaweb.net/yawiki/index.php?area=3DDB_Table

Yawiki: a collaborative online documentation system.
http://yawiki.com/

Yawp: a single-file foundation for PHP applications.
http://phpyawp.com/

On Tue, 2004-11-16 at 22:37, Paul M Jones wrote:
> On Nov 16, 2004, at 3:47 PM, Helgi Žormar wrote:
> 
>
> I have volunteered in the past, and will continue to do so on a
> standing basis, to set up a YaWiki <http://yawiki.com> installation for
> pear.php.net.  It's all PEAR all the time, except for using Savant
> <http://phpsavant.com> as its template system and Yawp
> <http://phpyawp.com> as its foundation, so I hope that's not a
> deal-breaker.  I did some work with Tobias Schlitt to get it up on a
> test machine, but there have been some problems with that box.

We want to integrate this into pearweb thus we can't use yawiki (well
okey we don't want to use it because of the deps outside of pear,
specially because of yawp)

> As regards a YaWiki installation, my own opinion is that each PEAR
> package would get its own area.  That results in a lot of areas, which
> means the default theme would not be useful; as such, it would need a
> modified theme for displaying all the various areas.  Not hard in a
> technical sense, but perhaps non-trivial from an organization and
> display perspective.  Authentication would be nice, but not required,
> if only so we can know who is doing what with documentation.

Authors will be able to choose if they want to use the wiki or not, thus
turning the feature on or off, at least the wiki for X package won't be
created unless the author turns the feature on for the first time.

Authentication won't be a problem, because it will be integrated into
pearweb :)

yaWiki will be probably the base of this, at least a side reference.

> So again:  this is me volunteering to get a YaWiki installation going
> on pear.php.net.

Note what I said above


--
Regards
Helgi

On Nov 16, 2004, at 4:59 PM, Helgi =DEormar wrote:

> We want to integrate this into pearweb thus we can't use yawiki (well
> okey we don't want to use it because of the deps outside of pear,
> specially because of yawp)

Good luck then.


--=20

Paul M. Jones

Savant: the simple alternative to Smarty for PHP.
http://phpsavant.com/

DB_Table: build RDBMS tables and XHTML forms in one PHP class.
http://wiki.ciaweb.net/yawiki/index.php?area=3DDB_Table

Yawiki: your collaborative online documentation system.
http://yawiki.com/

Yawp: a single-file foundation for PHP applications.
http://phpyawp.com/

Paul M Jones wrote:
>
> On Nov 16, 2004, at 4:59 PM, Helgi Žormar wrote:
> 
>
>
> Good luck then.

Well I would ponder that one for a bit.

For one the wiki can stay separated from the rest of pearweb. This was
actually something we agreed upon in amsterdam. Regardless of that
yawiki eats much more of our own dogfood than pearweb.

Finally its opensource and imho its a very good starting point. There
are some minor issues but things are getting along quite nicely and
especially the areamap and Text_Wiki basis are awesome foundations to
generate documentation.

regards,
Lukas

I did talk with Helgi about trac (which is an amazing piece of software abou
t
which I would not say it has drawbacks) but my main concern with writing our
own is,as helgi says, it will take a long time.

We can have a solution up in a shorter time by using yawiki. It would
not be as
fun as to develop our own solution but why bother where there are valid and
existing alternatives.

It's overkill to spend time coding when we can avoid it.

Arnaud.

----------------------------------------------------------------
This message was sent using IMP, the Internet Messaging Program.

arnaud@limbourg.com wrote:
> I did talk with Helgi about trac (which is an amazing piece of software
> about
> which I would not say it has drawbacks) but my main concern with writing
> our
> own is,as helgi says, it will take a long time.
>
> We can have a solution up in a shorter time by using yawiki. It would
> not be as
> fun as to develop our own solution but why bother where there are valid an
d
> existing alternatives.
>
> It's overkill to spend time coding when we can avoid it.

Agreed.  Paul's wiki works fine, the only thing that would have to be
changed is the basic look to match the rest of pear.php.net, and that's
just eye candy.  Plus we have the author as an active developer who I'm
sure can offer pointers, if not actual code, to do the job.

Greg

On Wed, 17 Nov 2004 11:40:58 -0500, Greg Beaver <cellog@php.net> wrote:
> arnaud@limbourg.com wrote:
>
> 
>
> Agreed.  Paul's wiki works fine, the only thing that would have to be
> changed is the basic look to match the rest of pear.php.net, and that's
> just eye candy.  Plus we have the author as an active developer who I'm
> sure can offer pointers, if not actual code, to do the job.
>

Hear hear.

--
Justin Patrin

On Tue Nov 16, 2004 at 10:5932PM +0000, Helgi =DEormar wrote:
> On Tue, 2004-11-16 at 22:37, Paul M Jones wrote: 
=20 
>=20
> We want to integrate this into pearweb thus we can't use yawiki (well
> okey we don't want to use it because of the deps outside of pear,
> specially because of yawp)

Who said that?  I for one would be very delighted to set up Paul's wiki
on e.g. wiki.pear.php.net - this way the wiki does not need to inherit
any code from the website, and at the same time the wiki can use the
existing user table for authentication. (Killing two birds with one
stone.)

--=20
- Martin                           Martin Jansen
http://martinjansen.com/