Hi all
It looks like [DOC] has failed miserably, it is of no use if only few
people use it for few commits.
Adding to the fact there is almost no activity in the documentations
we really need to find a better way to organize things.
Currently we have [DOC], (closed) bug reports, NEWS and wiki all
overlapping with each other.. not very attractive for newcomers.
Does anyone have any idea how we can organize things better and get
more people to document?
-Hannes
---------- Forwarded message ----------
From: Dmitry Stogov dmitry@php.net
Date: Wed, Oct 1, 2008 at 15:13
Subject: [PHP-CVS] cvs: php-src(PHP_5_3) / NEWS /ext/soap php_http.c
To: php-cvs@lists.php.net
dmitry Wed Oct 1 13:13:34 2008 UTC
Modified files: (Branch: PHP_5_3)
/php-src NEWS
/php-src/ext/soap php_http.c
Log:
Added ability to send user defined HTTP headers with SOAP request.
On Wed, Oct 1, 2008 at 10:39 AM, Hannes Magnusson <
hannes.magnusson@gmail.com> wrote:
Hi all
It looks like [DOC] has failed miserably, it is of no use if only few
people use it for few commits.
Adding to the fact there is almost no activity in the documentations
we really need to find a better way to organize things.
Currently we have [DOC], (closed) bug reports, NEWS and wiki all
overlapping with each other.. not very attractive for newcomers.Does anyone have any idea how we can organize things better and get
more people to document?-Hannes
Well,
Not sure how things were around here as I'm kinda new with docs but I might
have something.
I don't how it works internally neither how it works for new documentation.
But I've seen how Ubuntu Launchpad eases the work for translators. Have you
seen it? An online interface is much more attractive than this CVS thing.
Many of us - 'documentors' - (if not all) are programmers and used to use
CVS and other versioning system. But this takes some extra time that IMHO it
shouldn't. If you want to "spread the word" and get lots of people to help
in docs, I believe this kind of thing that Launchpad uses is a go. I'm very
well aware that this takes time and not every contributor may actually help
with good docs, but it could be moderated.
The quality of the actual docs is awesome, it's one of the best docs I've
ever seen. I don't want to miss that, so I'm all eyes and ears for this
thread.
Regards,
Thiago Henrique Pojda
[snip]
Many of us - 'documentors' - (if not all) are programmers and used to use
CVS and other versioning system. But this takes some extra time that IMHO it
shouldn't. If you want to "spread the word" and get lots of people to help
in docs, I believe this kind of thing that Launchpad uses is a go. I'm very
well aware that this takes time and not every contributor may actually help
with good docs, but it could be moderated.
[snip]
100% yes - the initial hurtle to getting new people writing docs is
teaching them docbook and cvs. You can whine all you want about "how
easy it is" - but it is NOT a zero learning curve and there are no good
(free) docbook tools on the systems most people use on the desktop (yes,
I mean Windows - and no people are not going to switch OS's for docbook
tools). Writing in XML is not a natural thing. An online interface
where people can edit docs would seriously boost people helping out.
Why do you think there are so many user notes in the PHP manual ;)
However...you will have to wade through the bad docs too. And I have no
solution for dealing with the "three million tools" issues.
Thanks,
Elizabeth Smith
Hi!
tools). Writing in XML is not a natural thing. An online interface
where people can edit docs would seriously boost people helping out.
Why do you think there are so many user notes in the PHP manual ;)
I think a web-based tool that would allow to generate standard docbook
pages (at least most primitive ones) and allow to edit certain sections
while supporting some basic stuff like paragraphs, links, styles
(italic, bold) etc. would be a HUGE help. I can write docbook and have
experience with it and I still find it annoying and hard to remember all
the details, I can only imagine how intimidating it appears to a newbie.
Easy tool allowing to contribute (and see the result without having to
install the whole toolchain?) would be an enormous boon. Of course, we'd
have to review/approve contributions, not have everybody do what they
please, but it's solvable.
So here's an idea for next Google Code project or for anybody having
free time :)
Stanislav Malyshev, Zend Software Architect
stas@zend.com http://www.zend.com/
(408)253-8829 MSN: stas@zend.com
tools). Writing in XML is not a natural thing. An online interface
where people can edit docs would seriously boost people helping out.
Why do you think there are so many user notes in the PHP manual ;)I think a web-based tool that would allow to generate standard docbook pages
(at least most primitive ones) and allow to edit certain sections while
supporting some basic stuff like paragraphs, links, styles (italic, bold)
etc. would be a HUGE help. I can write docbook and have experience with it
and I still find it annoying and hard to remember all the details, I can
only imagine how intimidating it appears to a newbie.
You were extremely unlucky when you wrote the intl docs, sorry for that! :)
Now we do however have skeletons for 99% cases, and even a 5minutes
tutorial on howto document exceptions[1].
NOTE: Most of the 5minutes are spent explaining how to build the docs.
Sure, an online editing tool would be great but I don't think that is
a realistic expectation for the time being. I'd rather want PHP5.3
documented before its release then someone spending all their time on
weird dirty mixed application that will probably not be ready until
PHP6.
Why do you think there are so many user notes in the PHP manual ;)
Speaking of which, we do also need volunteers to review them.
If you login to php.net (via bugsweb or
http://master.php.net/manage/users.php) you'll see three boxes
above(to the right) of all user notes:
- Edit (rarely used, mostly just to add <?php ?> tags for syntax
highlighting if people missed them - Reject the note (questions and stuff like that)
- Delete (wtf notes, bad code/advise, huge code...)
EVERYONE with a php.net account can do that and it would be greatly
appreciated if people would remove the horror notes when they
encounter them. It would even be more appreciated if extension
maintainers regularly review the notes attached to their extensions
(currently Derick is prettymuch the online who does that).
However...you will have to wade through the bad docs too. And I have no
solution for dealing with the "three million tools" issues.
I don't understand this argument.
All you need for building and view the documentations are 4things: CVS
client, PHP, text editor and a browser. All of which you have
installed already if you have any interest in PHP at all.
To build and view the docs follow these 6steps for the first time,
after you follow it once you only have to repeat 3 of the steps
- cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc
1b) cd phpdoc - php configure.php
- pear channel-discover doc.php.net && pear install doc.php.net/phd-beta
- phd -d .manual.xml -t chunkedhtml
- firefox html/index.html
- notepad en/reference/spl/spl/book.xml
Now repeat step 2, 4, and 5 after each change you make with you text editor.
If you can install PHP on your operating system then you can build the
docs and contribute.
-Hannes
[1] http://doc.php.net/php/dochowto/article.thequicky.exceptions.php
All,
I am what I guess you'd call a "newbie" - Elizabeth got me on this list
during ZendCon and though I've been following it I still have no idea how
the doc editing process works. I'm exactly who you want this kind of tool
for - a new contributor who is eager to contribute but unsure about how to
do so.
I've always been a fan of finding easy ways to do hard things. And I think
that this kind of system would be great for contributors, new and old alike.
My .02.
Brandon
On Wed, Oct 1, 2008 at 3:06 PM, Hannes Magnusson <hannes.magnusson@gmail.com
wrote:
On Wed, Oct 1, 2008 at 19:17, Elizabeth M Smith auroraeosrose@gmail.com
wrote:tools). Writing in XML is not a natural thing. An online interface
where people can edit docs would seriously boost people helping out.
Why do you think there are so many user notes in the PHP manual ;)I think a web-based tool that would allow to generate standard docbook
pages
(at least most primitive ones) and allow to edit certain sections while
supporting some basic stuff like paragraphs, links, styles (italic, bold)
etc. would be a HUGE help. I can write docbook and have experience with
it
and I still find it annoying and hard to remember all the details, I can
only imagine how intimidating it appears to a newbie.You were extremely unlucky when you wrote the intl docs, sorry for that! :)
Now we do however have skeletons for 99% cases, and even a 5minutes
tutorial on howto document exceptions[1].
NOTE: Most of the 5minutes are spent explaining how to build the docs.Sure, an online editing tool would be great but I don't think that is
a realistic expectation for the time being. I'd rather want PHP5.3
documented before its release then someone spending all their time on
weird dirty mixed application that will probably not be ready until
PHP6.Why do you think there are so many user notes in the PHP manual ;)
Speaking of which, we do also need volunteers to review them.
If you login to php.net (via bugsweb or
http://master.php.net/manage/users.php) you'll see three boxes
above(to the right) of all user notes:
- Edit (rarely used, mostly just to add <?php ?> tags for syntax
highlighting if people missed them- Reject the note (questions and stuff like that)
- Delete (wtf notes, bad code/advise, huge code...)
EVERYONE with a php.net account can do that and it would be greatly
appreciated if people would remove the horror notes when they
encounter them. It would even be more appreciated if extension
maintainers regularly review the notes attached to their extensions
(currently Derick is prettymuch the online who does that).However...you will have to wade through the bad docs too. And I have no
solution for dealing with the "three million tools" issues.I don't understand this argument.
All you need for building and view the documentations are 4things: CVS
client, PHP, text editor and a browser. All of which you have
installed already if you have any interest in PHP at all.To build and view the docs follow these 6steps for the first time,
after you follow it once you only have to repeat 3 of the steps
- cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc
1b) cd phpdoc- php configure.php
- pear channel-discover doc.php.net && pear install doc.php.net/phd-beta
- phd -d .manual.xml -t chunkedhtml
- firefox html/index.html
- notepad en/reference/spl/spl/book.xml
Now repeat step 2, 4, and 5 after each change you make with you text
editor.If you can install PHP on your operating system then you can build the
docs and contribute.-Hannes
[1] http://doc.php.net/php/dochowto/article.thequicky.exceptions.php
All,
I am what I guess you'd call a "newbie" - Elizabeth got me on this list
during ZendCon and though I've been following it I still have no idea how
the doc editing process works. I'm exactly who you want this kind of tool
for - a new contributor who is eager to contribute but unsure about how to
do so.
Would you mind being my test-subject then? :) 15minutes of your time
(plus couple of minutes to reply back) is all I ask for.
Its an easy task: Document the LogicException exception.
The exception has no methods (except for inherited once) and how to
document exception (from a-z, everything from obtaining the source to
building them to actually creating the doc) is already documented at
http://doc.php.net/php/dochowto/article.thequicky.exceptions.php
If it takes more then 15minutes you can quit and we'll have to try to
find better ways. If however you manage to do it in 15minutes or less,
please post the file to phpdoc@lists.php.net.
-Hannes
I'd be happy to serve as your test subject. I'll post back here when I've
done it (sometime this evening once I'm home from the office).
Brandon
On Wed, Oct 1, 2008 at 4:01 PM, Hannes Magnusson <hannes.magnusson@gmail.com
wrote:
On Wed, Oct 1, 2008 at 21:27, Brandon Savage brandon@brandonsavage.net
wrote:All,
I am what I guess you'd call a "newbie" - Elizabeth got me on this list
during ZendCon and though I've been following it I still have no idea how
the doc editing process works. I'm exactly who you want this kind of tool
for - a new contributor who is eager to contribute but unsure about how
to
do so.Would you mind being my test-subject then? :) 15minutes of your time
(plus couple of minutes to reply back) is all I ask for.
Its an easy task: Document the LogicException exception.The exception has no methods (except for inherited once) and how to
document exception (from a-z, everything from obtaining the source to
building them to actually creating the doc) is already documented at
http://doc.php.net/php/dochowto/article.thequicky.exceptions.phpIf it takes more then 15minutes you can quit and we'll have to try to
find better ways. If however you manage to do it in 15minutes or less,
please post the file to phpdoc@lists.php.net.-Hannes
Hi Hannes
2008/10/1 Hannes Magnusson hannes.magnusson@gmail.com:
tools). Writing in XML is not a natural thing. An online interface
where people can edit docs would seriously boost people helping out.
Why do you think there are so many user notes in the PHP manual ;)I think a web-based tool that would allow to generate standard docbook pages
(at least most primitive ones) and allow to edit certain sections while
supporting some basic stuff like paragraphs, links, styles (italic, bold)
etc. would be a HUGE help. I can write docbook and have experience with it
and I still find it annoying and hard to remember all the details, I can
only imagine how intimidating it appears to a newbie.You were extremely unlucky when you wrote the intl docs, sorry for that! :)
Now we do however have skeletons for 99% cases, and even a 5minutes
tutorial on howto document exceptions[1].
NOTE: Most of the 5minutes are spent explaining how to build the docs.Sure, an online editing tool would be great but I don't think that is
a realistic expectation for the time being. I'd rather want PHP5.3
documented before its release then someone spending all their time on
weird dirty mixed application that will probably not be ready until
PHP6.Why do you think there are so many user notes in the PHP manual ;)
Speaking of which, we do also need volunteers to review them.
If you login to php.net (via bugsweb or
http://master.php.net/manage/users.php) you'll see three boxes
above(to the right) of all user notes:
- Edit (rarely used, mostly just to add <?php ?> tags for syntax
highlighting if people missed them- Reject the note (questions and stuff like that)
- Delete (wtf notes, bad code/advise, huge code...)
EVERYONE with a php.net account can do that and it would be greatly
appreciated if people would remove the horror notes when they
encounter them. It would even be more appreciated if extension
maintainers regularly review the notes attached to their extensions
(currently Derick is prettymuch the online who does that).However...you will have to wade through the bad docs too. And I have no
solution for dealing with the "three million tools" issues.I don't understand this argument.
All you need for building and view the documentations are 4things: CVS
client, PHP, text editor and a browser. All of which you have
installed already if you have any interest in PHP at all.To build and view the docs follow these 6steps for the first time,
after you follow it once you only have to repeat 3 of the steps
- cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc
1b) cd phpdoc- php configure.php
- pear channel-discover doc.php.net && pear install doc.php.net/phd-beta
Actually this isn't always as easy on Windows, mainly because the
go-pear seems to not like Windows at all, I still havn't been able to
install pear with go-pear.
To install PhD I had to manually edit the phd.bat for it to work.
- phd -d .manual.xml -t chunkedhtml
- firefox html/index.html
- notepad en/reference/spl/spl/book.xml
Now repeat step 2, 4, and 5 after each change you make with you text editor.
If you can install PHP on your operating system then you can build the
docs and contribute.-Hannes
[1] http://doc.php.net/php/dochowto/article.thequicky.exceptions.php
--
--
Kalle Sommer Nielsen
Hi Hannes
2008/10/1 Hannes Magnusson hannes.magnusson@gmail.com:
- cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc
1b) cd phpdoc- php configure.php
- pear channel-discover doc.php.net && pear install doc.php.net/phd-beta
Actually this isn't always as easy on Windows, mainly because the
go-pear seems to not like Windows at all, I still havn't been able to
install pear with go-pear.
Why not? Getting any errors? I thought it was installed by default by
the installer?
-Hannes
2008/10/2 Hannes Magnusson hannes.magnusson@gmail.com:
Hi Hannes
2008/10/1 Hannes Magnusson hannes.magnusson@gmail.com:
- cvs -d:pserver:cvsread@cvs.php.net/repository co phpdoc
1b) cd phpdoc- php configure.php
- pear channel-discover doc.php.net && pear install doc.php.net/phd-beta
Actually this isn't always as easy on Windows, mainly because the
go-pear seems to not like Windows at all, I still havn't been able to
install pear with go-pear.Why not? Getting any errors? I thought it was installed by default by
the installer?
I do not use the installer, I simply just extra php to the folder I
want to use it from. When I use:
C:\PHP_5_2>go-pear
It asks me to install a system or local wide install, then it comes up
with some configuratives where the path to CLI php.exe always is
missing. If I press Enter to continue it just shows the same list of
paths, if I type all after have configured path 12 (to CLI php.exe),
it will end up with this error:
1-12, 'all' or Enter to continue: all
Installation base ($prefix) [Inputfejl: Der er ikke noget filtypenavn
i "C:\Users\Kalle".] :
(Input error: There is no filetype name in "C:\Users\Kalle")
I guess its because the installer doesn't support folders with spaces
as the directory is called "C:\Users\Kalle Sommer Nielsen...."
So you cannot get further or atleast I can't because my username has
spaces. I had to edit the phd.bat manually to make it work, not that
it was any major but anyway.
-Hannes
--
Kalle Sommer Nielsen
Hello all,
An online editing mechanism was discussed and started[1] but let's be
honest here and stare at the larger problem. The documentation team is
on extended holiday and why? I don't know... maybe it's cyclical? Or
maybe we need a larger marketing budget. But really if making it
easier to inject words into the manual is seen as the main problem
here then great, that sounds easy to fix, but writing good
documentation is time consuming and I guess many humans prefer not
doing it at all even though it's an art too. But maybe removing the "I
don't have time to setup/test yet another tool chain" excuse is a good
start. The new doc build system has gone a long way to do this.
We recently reviewed the doc TODO situation and one of the first tasks
is streamlining the HOWTO because it's a bit lengthy and dated. As for
the required tool chain it's not too difficult anymore, and DocBook
knowledge and special tools are not needed except to know XML <para>
is like a <p> in HTML. Basically. Almost.
The online editor thread with demo:
[1] http://markmail.org/message/xchvvhk4hlvg33a3
Regards,
Philip
Hannes,
I think both Thiago and Elizabeth are correct. Call me old-hat: I
prefer CVS.... but I'm well aware that it's a daunting task to learn
that new technology for people who would otherwise not use it. In
fact, most projects - including PHP - are moving away from CVS, in
favor of SVN, Git, et cetera. If we don't encourage new people to
assist in the documentation - and foster them in the process - the
docs will suffer. And if the docs suffer, the language is surely
going to lose it's position quickly.
I propose that the idea of creating a new web-based interface
moves forward, and that we put out a call for volunteers to build the
new system. I'll even take on the responsibility of leading or
co-managing the project, and will donate hardware and bandwidth for
the development of the new system.
Even to build a system to integrate with the existing one would
not be too difficult. Take ideas from the Wiki project, et al, and we
can have the results output as XML files if we really want to. The
project could be as small as to fill the niche to offer an easy-to-use
web interface that uses BBCode-like markup and auto-commits to the CVS
repo, or as vast as creating a new, proprietary system.
If the proposal from here moves forward, we should set up a
convenient time when the initial Working Group can meet on IRC or
another medium to set the foundation and iron-out the initial details.
--
</Daniel P. Brown>
More full-root dedicated server packages:
Intel 2.4GHz/60GB/512MB/2TB $49.99/mo.
Intel 3.06GHz/80GB/1GB/2TB $59.99/mo.
Intel 2.4GHz/320/GB/1GB/3TB $74.99/mo.
Dedicated servers, VPS, and hosting from $2.50/mo.
Elizabeth M Smith wrote:
[snip]
Many of us - 'documentors' - (if not all) are programmers and used to use
CVS and other versioning system. But this takes some extra time that IMHO it
shouldn't. If you want to "spread the word" and get lots of people to help
in docs, I believe this kind of thing that Launchpad uses is a go. I'm very
well aware that this takes time and not every contributor may actually help
with good docs, but it could be moderated.[snip]
100% yes - the initial hurtle to getting new people writing docs is
teaching them docbook and cvs. You can whine all you want about "how
easy it is" - but it is NOT a zero learning curve and there are no good
(free) docbook tools on the systems most people use on the desktop (yes,
I mean Windows - and no people are not going to switch OS's for docbook
tools). Writing in XML is not a natural thing. An online interface
where people can edit docs would seriously boost people helping out.
Why do you think there are so many user notes in the PHP manual ;)
However...you will have to wade through the bad docs too. And I have no
solution for dealing with the "three million tools" issues.
Hi,
I think Hannes was also talking about the fact that committers to CVS
are not using [DOC] in their commit messages.
I agree with Liz's appraisal of setting up docs for documenting. This
could actually be solved with a minimal VMWare appliance that is
pre-setup with everything we need to do the docs (not sure how hard that
is to do). VMware works great on windows and the version we would need
is free.
An online interface would be useful, but would it really occur to the
developers committing to php's cvs to use it? I'm not so sure. It
takes me almost as long, sometimes twice as long to document the things
that I write, this is the main problem from a coder's perspective: free
time. I would almost rather have short summaries inside /* */ of how
things work close to the lines that implement them, it would make it
easier to debug other people's code as well as make documenting small
changes easier. Big changes perhaps should be documented with either
quick README.DOCUMENTING files, or some other quick-and-dirty situation
in the source repo for those who are not yet comfortable in docbook, or
in English (as both native and non-native speakers can attest, it's hard
to translate PHP into English :).
This was done with namespaces, and it made documenting easier, right?
Greg
2008/10/1 Greg Beaver greg@chiaraquartet.net:
Elizabeth M Smith wrote:
[snip]
Many of us - 'documentors' - (if not all) are programmers and used to use
CVS and other versioning system. But this takes some extra time that IMHO it
shouldn't. If you want to "spread the word" and get lots of people to help
in docs, I believe this kind of thing that Launchpad uses is a go. I'm very
well aware that this takes time and not every contributor may actually help
with good docs, but it could be moderated.[snip]
100% yes - the initial hurtle to getting new people writing docs is
teaching them docbook and cvs. You can whine all you want about "how
easy it is" - but it is NOT a zero learning curve and there are no good
(free) docbook tools on the systems most people use on the desktop (yes,
I mean Windows - and no people are not going to switch OS's for docbook
tools). Writing in XML is not a natural thing. An online interface
where people can edit docs would seriously boost people helping out.
Why do you think there are so many user notes in the PHP manual ;)
However...you will have to wade through the bad docs too. And I have no
solution for dealing with the "three million tools" issues.Hi,
I think Hannes was also talking about the fact that committers to CVS
are not using [DOC] in their commit messages.I agree with Liz's appraisal of setting up docs for documenting. This
could actually be solved with a minimal VMWare appliance that is
pre-setup with everything we need to do the docs (not sure how hard that
is to do). VMware works great on windows and the version we would need
is free.An online interface would be useful, but would it really occur to the
developers committing to php's cvs to use it? I'm not so sure. It
takes me almost as long, sometimes twice as long to document the things
that I write, this is the main problem from a coder's perspective: free
time. I would almost rather have short summaries inside /* */ of how
things work close to the lines that implement them, it would make it
easier to debug other people's code as well as make documenting small
changes easier. Big changes perhaps should be documented with either
quick README.DOCUMENTING files, or some other quick-and-dirty situation
in the source repo for those who are not yet comfortable in docbook, or
in English (as both native and non-native speakers can attest, it's hard
to translate PHP into English :).This was done with namespaces, and it made documenting easier, right?
Greg
Hi, I know I'm a small voice here, but try to follow my reasoning.
The core devs write C code. The compile C code. They test it. Now, in
my mind they are going to be using PHP code to test it (yes?).
So, these "tests" are the best documentation you can get. They show
you HOW it works, not from the internals perspective, but from the
userland perspective (how do I use this function/method). Having to
test it works requires an understanding of how it works.
So, MAYBE, the core-devs could write userland code examples. Covering
all the methods/parameters. I'm SURE (ahem) they already have this
otherwise, how do they know there code works.
A few additional comments to the code would help everyone. Not reams
like I seem to produce on such a small topic (I'm wordy, get over it).
I'm not talking about code coverage or unit tests here, they serve a
different function. Knowing how your code will behave with broken data
is one thing, but making sure it works with valid data is just as
valid test.
Is there a way to get just examples for all the functions?
If the core-devs tests are good enough to make sure the code works,
then it should be good enough for users to work from.
Richard.
--
Richard Quadling
Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731
"Standing on the shoulders of some very clever giants!"
I agree with Liz's appraisal of setting up docs for documenting. This
could actually be solved with a minimal VMWare appliance that is
pre-setup with everything we need to do the docs (not sure how hard that
is to do). VMware works great on windows and the version we would need
is free.
As Hannes said: All you need is PHP, PhD and a docbook checkout. The
later one will be outdated anyways when fetching the VMWare-Image and I
assume it's harder to learn how to use the VMWare image than installing
these thing, never did that on Windows, but on my *nix it's a shot task
to get it running.
The hard part is not installation of tools but writing the docs
themselves.
johannes