Everything

php

Home » Project » Newsgroups » php.internals » Improving the documentation »

Improving the documentation

php.internals

Mehdi Achour

19 years ago

Hello internals,

I've been helping with PHP documentation for 4 years now, and I still
can't help the fact that a loooot of things are not documented, that
our/my way of handling the PHP documentation update is not accurate, nor
productive, nor bug free at all.

Personally, I try to follow commits on php.cvs, bug reports, Change
Log?, user notes on the online manual.. but I still have the feeling of
missing a lot of changes. After a year away from the project, I have
_no_ clue what was added, when, and whether it was added to our
documentation or not.

I know that you developers are willing to help a lot with it, but that
you cannot manage to save the spare time needed to do it the right way.
That's why I would like to propose a simple/small/timeless change in
your CVS commit messages: If you feel that the change need to be
documented, place the @doc keyword at the end of your message log entry.

And if you feel like telling us more about what you changed, point us to
some online resource or whatever. Simply add that after the @doc tag.
This additional comment is optional, and you don't need to bother if the
change is obvious, or if you simply don't feel like doing it ATM.

This small @doc tag could _slightly_ improve/optimize/sanitize our work
on the documentation. By adding some SQL logging in loginfo.pl, and
storing the following:

* date: commit date
* login: CVS account of the developer
* branch: CVS branch
* files: Changed files
* commit: Commit message before @doc
* desc : Optional developer description after @doc


We would be able to have an interface displaying a dynamic phpdoc TODO,
with some nice features like a search by PHP version, extension,
assignee, keywords..

Additionally, we can imagine adding an online help feature on the
interface, by setting a “help” flag on some hardly understandable
change, to have login@php.net notified of our need for enlightenment.

Any thoughts ?

Mehdi Achour

Nuno Lopes

19 years ago

> I know that you developers are willing to help a lot with it, but that you
> cannot manage to save the spare time needed to do it the right way. That's
> why I would like to propose a simple/small/timeless change in your CVS
> commit messages: If you feel that the change need to be documented, place
> the @doc keyword at the end of your message log entry.
>
> And if you feel like telling us more about what you changed, point us to
> some online resource or whatever. Simply add that after the @doc tag. This
> additional comment is optional, and you don't need to bother if the change
> is obvious, or if you simply don't feel like doing it ATM.
>
> This small @doc tag could _slightly_ improve/optimize/sanitize our work on
> the documentation. By adding some SQL logging in loginfo.pl, and storing
> the following:

bump, just to make sure this idea isn't forgot :)
It is pretty important to the doc team to have a list of commits that need
documentation. Currently I accomplish this by using my local inbox folder,
but this is not very efficient (nor shareable).

I don't program Perl for more than 5 years now, so I don't feel confortable
making those changes, so in the next step we need a volunteer to do it ;)

Nuno

P.S.: uhm, instead of changing the the loginfo.pl script we could have
either have a news.php.net crawler bot or an e-mail parser...

Ronald Chmara

19 years ago

On Jan 27, 2007, at 8:26 AM, Mehdi Achour wrote:

> Hello internals,
> I've been helping with PHP documentation for 4 years now, and I
> still can't help the fact that a loooot of things are not
> documented, that our/my way of handling the PHP documentation
> update is not accurate, nor productive, nor bug free at all.

I think it's been ~7 years of off and on work for me... same as it
ever was. I do think it's *much* more productive and accurate than it
was 7 years ago, though. Not quite bug-free, yet.

(You think it's bad now...)

> Personally, I try to follow commits on php.cvs, bug reports, Change
> Log?, user notes on the online manual.. but I still have the
> feeling of missing a lot of changes. After a year away from the
> project, I have _no_ clue what was added, when, and whether it was
> added to our documentation or not.

You are in the same boat as me..... The dunes change, but the sands
are always shifting. I might have been away for n years. Much has
changed, and much has not.

> I know that you developers are willing to help a lot with it, but
> that you cannot manage to save the spare time needed to do it the
> right way. That's why I would like to propose a simple/small/
> timeless change in your CVS commit messages: If you feel that the
> change need to be documented, place the @doc keyword at the end of
> your message log entry.

Scenario one:
All behavior changes must be documented, this tag is always there,
and thus not useful.

Scenario two:
Developers decide when changes are "important" enough to be
documented, and tag as such, in which case we go back to...

Scenario three:
The problem of developers who don't think documentation is needed for
their changes.

In the end, I often wonder if this is documentation issue, or a
developer issue. Developers read the code, and often don't need *any*
documentation. Our end users read a manual page, and wonder what a
"bool" or "int" is, as a very large number of our users are fairly
new to the whole subject matter.

(side joke, does PHP have a zool(), destroyer of all world (global)
variables?)

Anyways, to me, the real challenge of working on the PHP docs is not
getting programmers to feed us reliable, consistent, data all the
time (they won't),  but rather, helping out our end users who don't
read source code.

Vanity devs will want us to document everything, quiet devs will
never tag it.

In the end, the doc team still has to fix it.

-Ronabop

Rasmus Lerdorf

19 years ago

We, and by we I mean all of us who write code and hope that divine
intervention will take care of the documentation, need to do a better
job helping out divinity.  A DOC tag in cvs commit messages seems like a
small and easy thing for us to add to the process, so if you feel that
will be enough to make things easier, let's do that.

Perhaps we can do more though.  Maybe you guys could periodically update
internals on problem areas in the docs.  Places where you feel things
are vague and really could use the guy who wrote the code to get off his
ass and explain how it works.  Or maybe we could get everyone who reads
internals to pick a page or two in the manual on something they are
intimately familiar with and go over it in detail and feed suggestions
back to phpdoc@

-Rasmus


Ronald Chmara wrote:

Lukas Kahwe Smith

19 years ago

Rasmus Lerdorf wrote:

> Perhaps we can do more though.  Maybe you guys could periodically update
> internals on problem areas in the docs.  Places where you feel things
> are vague and really could use the guy who wrote the code to get off his
> ass and explain how it works.  Or maybe we could get everyone who reads
> internals to pick a page or two in the manual on something they are
> intimately familiar with and go over it in detail and feed suggestions
> back to phpdoc@

If deemed useful, we can of course devote a section for this in the
unofficial phptodo wiki:
http://oss.backendmedia.com/PHPTODO/

regards,
Lukas

Wez Furlong

19 years ago

I tweaked loginfo.pl so that if the commit message contains [DOC],
phpdoc@ will be Cc'd.
Hopefully that'll help in some small way.

--Wez.

On 2/10/07, Rasmus Lerdorf <rasmus@lerdorf.com> wrote:

Etienne Kneuss

19 years ago

Hi,

I also made a mailing list scanner[1] that fills a DB on doc.php.net.
Every entries can then be commented, tagged as TODO etc...
The scanner itself is ready, the interface still need some work.

Maybe a mix of both ?

[1] http://colder.ch/repository/php/php.net/cvslogger.php

Wez Furlong wrote:

> I tweaked loginfo.pl so that if the commit message contains [DOC],
> phpdoc@ will be Cc'd.
> Hopefully that'll help in some small way.
>
> --Wez.
>
> On 2/10/07, Rasmus Lerdorf <rasmus@lerdorf.com> wrote:
>> We, and by we I mean all of us who write code and hope that divine
>> intervention will take care of the documentation, need to do a better
>> job helping out divinity.  A DOC tag in cvs commit messages seems like a
>> small and easy thing for us to add to the process, so if you feel that
>> will be enough to make things easier, let's do that.
>>
>> Perhaps we can do more though.  Maybe you guys could periodically update
>> internals on problem areas in the docs.  Places where you feel things
>> are vague and really could use the guy who wrote the code to get off his
>> ass and explain how it works.  Or maybe we could get everyone who reads
>> internals to pick a page or two in the manual on something they are
>> intimately familiar with and go over it in detail and feed suggestions
>> back to phpdoc@
>>
>> -Rasmus
>>
>>
>> Ronald Chmara wrote:
>> > On Jan 27, 2007, at 8:26 AM, Mehdi Achour wrote:
>> >> Hello internals,
>> >> I've been helping with PHP documentation for 4 years now, and I still
>> >> can't help the fact that a loooot of things are not documented, that
>> >> our/my way of handling the PHP documentation update is not accurate,
>> >> nor productive, nor bug free at all.
>> >
>> > I think it's been ~7 years of off and on work for me... same as it
>> ever
>> > was. I do think it's *much* more productive and accurate than it was 7
>> > years ago, though. Not quite bug-free, yet.
>> >
>> > (You think it's bad now...)
>> >
>> >> Personally, I try to follow commits on php.cvs, bug reports, Change
>> >> Log?, user notes on the online manual.. but I still have the feeling
>> >> of missing a lot of changes. After a year away from the project, I
>> >> have _no_ clue what was added, when, and whether it was added to our
>> >> documentation or not.
>> >
>> > You are in the same boat as me..... The dunes change, but the sands
>> are
>> > always shifting. I might have been away for n years. Much has changed,
>> > and much has not.
>> >
>> >> I know that you developers are willing to help a lot with it, but
>> that
>> >> you cannot manage to save the spare time needed to do it the right
>> >> way. That's why I would like to propose a simple/small/timeless
>> change
>> >> in your CVS commit messages: If you feel that the change need to be
>> >> documented, place the @doc keyword at the end of your message log
>> entry.
>> >
>> > Scenario one:
>> > All behavior changes must be documented, this tag is always there, and
>> > thus not useful.
>> >
>> > Scenario two:
>> > Developers decide when changes are "important" enough to be
>> documented,
>> > and tag as such, in which case we go back to...
>> >
>> > Scenario three:
>> > The problem of developers who don't think documentation is needed for
>> > their changes.
>> >
>> > In the end, I often wonder if this is documentation issue, or a
>> > developer issue. Developers read the code, and often don't need *any*
>> > documentation. Our end users read a manual page, and wonder what a
>> > "bool" or "int" is, as a very large number of our users are fairly new
>> > to the whole subject matter.
>> >
>> > (side joke, does PHP have a zool(), destroyer of all world (global)
>> > variables?)
>> >
>> > Anyways, to me, the real challenge of working on the PHP docs is not
>> > getting programmers to feed us reliable, consistent, data all the time
>> > (they won't),  but rather, helping out our end users who don't read
>> > source code.
>> >
>> > Vanity devs will want us to document everything, quiet devs will never
>> > tag it.
>> >
>> > In the end, the doc team still has to fix it.
>> >
>> > -Ronabop
>> >
>> > --PHP Internals - PHP Runtime Development Mailing List
>> > To unsubscribe, visit: http://www.php.net/unsub.php
>>
>

--
Etienne Kneuss
http://www.colder.ch
colder@php.net

Men never do evil so completely and cheerfully as
when they do it from a religious conviction.
-- Pascal

Mehdi Achour

19 years ago

Hello Wez,

Thanks for your action. BTW, we need to stick to one tag :) I proposed
@doc, you implemented [DOC] .. we should pick one syntax and stick to
it.

By the way, Etienne (cc'ed) started to work on the web interface I
described in my first email. You may want to get in touch with him to
help him get things working.

Maybe we could set up another newsgroup for the emails? (php.doc.todo)

Mehdi

On 2/10/07, Wez Furlong <kingwez@gmail.com> wrote:

Philip Olson

19 years ago

On Feb 10, 2007, at 8:38 AM, Rasmus Lerdorf wrote:

> We, and by we I mean all of us who write code and hope that divine
> intervention will take care of the documentation, need to do a better
> job helping out divinity.  A DOC tag in cvs commit messages seems
> like a
> small and easy thing for us to add to the process, so if you feel that
> will be enough to make things easier, let's do that.
>
> Perhaps we can do more though.  Maybe you guys could periodically
> update
> internals on problem areas in the docs.  Places where you feel things
> are vague and really could use the guy who wrote the code to get
> off his
> ass and explain how it works.  Or maybe we could get everyone who
> reads
> internals to pick a page or two in the manual on something they are
> intimately familiar with and go over it in detail and feed suggestions
> back to phpdoc@

There are 137 open documentation bugs and many of these require PHP
internals intervention. I don't know the best way to help that happen
aside from maybe going through them all and updating the summaries
(and appending categories to those summaries) but then what? A
question: What would be a productive way to help get 'er done? Side
note: Is it time to completely overhaul php-bugs-web? (I'm not
volunteering!)

Those ideas about doing more are nice because the DOC tag is a good
start but additional collaboration is needed. Part of the
documentation teams job can easily be organizing information requests
so the developers can work efficiently. If that means, as suggested
above, periodic updates then we'll for sure do it. A few come to mind
already. It's exciting to see this thread blossom! I hope everyone
feels free to brainstorm... ALL ideas are welcome!

A rough unofficial related report:

Undocumented functions (only proto, etc.): ~815
Functions not in the manual: ~118 (granted ~half are ref.unicode)
Functions missing examples: ~2490
Open doc bugs: 137

To those interested in seeing where exactly these statistics came
from, have a look: http://doc.php.net/php/

Regards,
Philip

Lukas Kahwe Smith

19 years ago

Philip Olson wrote:

> There are 137 open documentation bugs and many of these require PHP
> internals intervention. I don't know the best way to help that happen
> aside from maybe going through them all and updating the summaries (and
> appending categories to those summaries) but then what? A question: What
> would be a productive way to help get 'er done? Side note: Is it time to
> completely overhaul php-bugs-web? (I'm not volunteering!)

Maybe once you have a clean summary post one bug per day either here or
ask in #php.pecl.

regards,
Lukas

Richard A. Quadling

19 years ago

> -----Original Message-----
> From: Philip Olson [mailto:philip@roshambo.org]
> Sent: Sunday, February 11, 2007 7:10 AM
> To: Rasmus Lerdorf
> Cc: Ronald Chmara; Mehdi Achour; internals@lists.php.net;
> phpdoc@lists.php.net
> Subject: Re: [PHP-DOC] Re: [PHP-DEV] Re: [PHP-DOC] Improving
> the documentation
> Those ideas about doing more are nice because the DOC tag is
> a good start but additional collaboration is needed. Part of
> the documentation teams job can easily be organizing
> information requests so the developers can work efficiently.
> If that means, as suggested above, periodic updates then
> we'll for sure do it. A few come to mind already. It's
> exciting to see this thread blossom! I hope everyone feels
> free to brainstorm... ALL ideas are welcome!

All ideas? With regard to missing examples, how about incorporating some
of the unit tests?

From what I understand, one of the purposes of unit testing is to
actually test the function/method and to make sure it still works after
amendments to the code.

So, if it is good enough for unit testing, how much effort is it to use
them as an example?

Admittedly, the bigger picture could be missing.

So, as developers want to write code (in preference to writing
documentation), if they were able to provide working examples, rather
than wordy documentation, at least there would be some PHP (rather than
C) code available for the documentors to see what is going on and how
things work.

I assume the developers test their own code so they must have SOME PHP
examples.

If these where named according to something like this ...

/php-src/ext/module/examples/function_nn.php
/php-src/ext/module/examples/extension_nn.php

Where :

ext is the name of the extension,
function is the name of the function or method,
nn is a simple count (01, 02, 03, etc)
extension is for more global examples that would appear on the ext's
main page rather than on a function/method page....

These examples COULD include a tag or a comment for versioning.


The idea here is to allow the developers to show the world using PHP
what their extension does. They say a picture is worth a thousand words.
I think, in some cases, an example would also work. Ideally, the
examples should also include some output (that's the hard part) so the
example could be cut'n'pasted and tested and the user could see that the
output matches. A little bit sort of like a unit test.

Then the documentation team could see proper/expected usage. It COULD
also make more unit tests available.

If the developers primary language is NOT English, then that's not an
issue as the PHP language would be the common denominator.

By having the examples as separate files, they could actually be tested
to make sure they work (not exactly sure how to automate this).
Capturing output could also be done automatically. Image function
examples could create the images used for the manual, etc.

The possibilities are endless. And the start point is to get developers
to write a little bit more code rather than writing documentation.

Regards,

Richard Quadling.

Mehdi Achour

19 years ago

As Phillip stated, we already have a set of tools that points us to
the problems in the documentation.

We also are switching the documentation to a clearer format, which we
help us to have more accurate results on this, while making docs
editing simpler for you guys.

I've noted your periodical update proposal. Indeed, a wiki page on
phpdoc.info could help to prepare a weekly email to internals (with
some statistics like the one Phillip gave us).

Thank you all for your replies, I'm happy to see that the snowball
effect started!

Mehdi

On 2/10/07, Rasmus Lerdorf <rasmus@lerdorf.com> wrote:

Lukas Kahwe Smith

19 years ago

Mehdi Achour wrote:

> Thank you all for your replies, I'm happy to see that the snowball
> effect started!

Just make sure that you take this momentum and directly contact people
who's offers you want to take up so that real world effect can be
derived from all of the offers.

regards,
Lukas

Rasmus Lerdorf

19 years ago

Phillip and I had a chat about this last night and I think we have a
strategy for appealing to the geek in all of us.

-Rasmus

Mehdi Achour wrote:

Richard Lynch

19 years ago

On Sat, February 10, 2007 5:41 am, Ronald Chmara wrote:

> Scenario one:
> All behavior changes must be documented, this tag is always there,
> and thus not useful.

I beg to differ.

If every change was documented to the degree that it needed
documentation, the tag would be useful still:

USEFUL:
- ops
+ oops
@doc Fixed typo in comments

NOT SO MUCH:
+ /* pretend I typed 40 lines of really hacky C code here */
@doc Frobished the frobisher

> Scenario two:
> Developers decide when changes are "important" enough to be
> documented, and tag as such, in which case we go back to...
>
> Scenario three:
> The problem of developers who don't think documentation is needed for
> their changes.

Is anybody really that... naive?

It seems to me that giving the developer the opportunity to easily
give the Doc Team SOME CLUE what the heck they were thinking is a Good
Idea.

> In the end, I often wonder if this is documentation issue, or a
> developer issue. Developers read the code, and often don't need *any*
> documentation. Our end users read a manual page, and wonder what a
> "bool" or "int" is, as a very large number of our users are fairly
> new to the whole subject matter.

Most of them are in the middle of that...

> (side joke, does PHP have a zool(), destroyer of all world (global)
> variables?)

No, but you can implement this in User Code:

function zool(){
foreach($_GLOBALS as $k => $v){
unset($k);
}
unset($_GLOBALS);
}

:-)

--
Some people have a "gift" link here.
Know what I want?
I want you to buy a CD from some starving artist.
http://cdbaby.com/browse/from/lynch
Yeah, I get a buck. So?