PHP Documentation - Re: [PHP-DOC] Re: [PHP-DEV] Summer of Code

Author

Re: [PHP-DOC] Re: [PHP-DEV] Summer of Code

anatoly techtonik

2006-05-02, 6:59 pm

||*()*|| Hi, Nuno.
[color=darkred]

NL> Ah great! :)

NL> This year I might participate. I would like to do something in the core or
NL> even in the zend engine. I'll think in something.. (I'm also open to
NL> suggestions, of course).

NL> I would also like to propose a project related with the documentation team,
NL> which is very useful to us:
NL> * working on livedocs (rewriting the indexer, improving docbook compat,
NL> pear/gtk/smarty docs support, php 6 support, etc..)

Too bad your letter was lost in my usual phpdoc traffic. I wish we
could discuss this this a little bit earlier and review RFC/ with howto/
to analyse the progress so far and plan the future steps for PHPDOC.
This can help to guide sporadic PHPDOC tools development to make it more
popular and clear among those potential ones from millions of PHP addicts,
who is able and willing to help given that bottlenecks and stone blocks are
removed from the steep enough learning curve.

What I would like to see is:
1. Visibility of PHPDOC software architecture and process

I guess for phpdoc/ howto is a good draft, but lacks some
pictures. There can be additional chapter about how the
docs are born and uploaded and who is involved in the
process. Clear entrypoint to PHPDOC tools world is also
must have, because amount of information can be frustating.

2. Issue tracker

PHP bugtracker is good, well-tested, but not suitable for
maintaining issues. Issue (in my vision) can not be "bogus".
Issue is a step in more general plan and it need to be
resolved for the plan to be succeeded. Plan is an idea.
Ideas can be possible or impossible. Possible ideas depend
on resources. Impossible ideas are just that - impossible,
but still contain explanation why (stoneblock, like on
graveyards). Possible ideas, which depend on external factors
can be frozen to wait for these factors (blockers) to resolve.
Ideas can be frozen also if resources are scarce or just
unavailable. To freeze an idea some current status must be
written. Usually this means that somebody else can pick up
the idea, resolve blocker issue and he will have every
available information to fix it. Ideas are not proposals
- idea is a more mild variant of requirement and issue within
idea is a detailed specification of what should be done for
this idea to be archieved. Idea status can be refactored -
you can always write a different status to outline steps
in development, keep duscussion focused. Discussions can be
filtered accordingly, but you can always dig down levels
to initial discussions. Input for "notes" or additions to
issues can be everything - from emails to SVN/CVS commits,
quotes and links, but with periodical link/consistency checks
and perhaps even local copies of necessary information (cache).
This can be used for gathering requirements and elaboration.
Everything can be RSS'ed.

2. CVS to SVN, SVN as a Livedocs backend

I can be a little bit misleaded, but it seems to me that
SVN can be accessed from web application and we can use
this ability. First idea is online patch generation, where
user can edit the page (like in wiki), but instead of
page text he is presented with XML source and preview
is basically the a patch, which is after automatically
assigned to an issue. Patch can be approved and directly
applied to SVN.

3. Livedocs AJAX

I do not know the status of livedocs and the abilities
of this system to provide describe, validate and modify
docbook structure. But if this functionality is suitable, we
can try to move it into AJAX to provide some WYSIWYG features
keeping internal XML structure in 1:1 with presentation on a
visually edited web page.

4. PHP.NET API, Web-Services and visual tools

Just for the Summer of Code. It would be nice to see PHP core to
invent some advanced techniques (?PHP4EE) to let PHP technology
make the step from scripting to modeling applications, to use
abstraction as a survival instrument in complex projects. phpdoc/
is such complex project.

It is a lot of work and it is more research work than actual coding.

a. What would we like to achieve?
b. How this could be achieved?
c. What do we have?
d. What is the current status?

a. Convenient tools to communicate, edit PHPDOC documention,
build it and control the process. Easy for new developers.
b. Time, time and time (given you know what to do and how to)
detailed plan, clear idea, steps (milestones), user feedback,
requirements gathering, strong community support. Perhaps even
commercial development support.
c. Very busy and few tools developers, parts of tools code,
parts of phpdoc/ tools decription, high-volume mailing list, a
lot of sites.
d. As far as I know the only way to get the status of phpdoc/
tools is to monitor mailing list and ask questions. You can also
try to look for files on CVS and especially RFC/ folder, but
the latter seems to be greatly outdated. There is no priority/
entrypoint tasks, which will make it clear what should be done
in the first place, why it isn't done yet. There is no clear
visibility in phpdoc/ process, but almost total freedom to
hack. =)

t
--

Nuno Lopes

2006-05-03, 6:59 pm

> 2. CVS to SVN, SVN as a Livedocs backend
>
> I can be a little bit misleaded, but it seems to me that
> SVN can be accessed from web application and we can use
> this ability. First idea is online patch generation, where
> user can edit the page (like in wiki), but instead of
> page text he is presented with XML source and preview
> is basically the a patch, which is after automatically
> assigned to an issue. Patch can be approved and directly
> applied to SVN.

No SVN please! I don't like it :)
didou, which isn't very active these days had a patch in his server to do
this for the French team. (but it mailed the patch to the list).

And yes, having an automatic patch center would be great. (any student here
to apply to SoC? :) With such tool we could commit a patch clicking just on
a buton. But the old problem is that we never have enough time to implement
everything we want.. First livedocs, other stuff later IMHO.

> 3. Livedocs AJAX
>
> I do not know the status of livedocs and the abilities
> of this system to provide describe, validate and modify
> docbook structure. But if this functionality is suitable, we
> can try to move it into AJAX to provide some WYSIWYG features
> keeping internal XML structure in 1:1 with presentation on a
> visually edited web page.

It can validate xml only (which is done by libxml).
We have already explored some applications that provide such WYSIWYG
feautures, but I didn't like any of them :)
There is the bitflux open-source editor, but it needed to be ported to
docbook (and I'm a noob in XSLT and javascript). There is also a new editor
that one of mine colleagues as done in last year's SoC, but I haven't tested
it yet properly (http://www.xwiki.org/xwiki/bin/view/Dev/DHTMLWysiwyg)

Nuno

Sponsored Links