Re: [PHP-DOC] Re: [PHP-WEBMASTER] Re: [PHP-DOC] Improving User Notes In The Manual -- First Steps
On Mon, Sep 10, 2012 at 11:41 AM, Sherif Ramadan wrote: > On Mon, Sep 10, 2012 at 1:27 PM, Daniel Brown wrote: >> So as long as you want to run lead on it, Sherif, and it's >> something we can easily disable entirely, should some unforeseen >> consequences arise as a result of the new voting/reporting features, >> then you can count me in for a plus-one. > I have no problem taking lead on it. I'm in it for the long-run and > hopefully looking forward to finding even better ways to improve > notes. It's been a long time since I crawled through the thousands of notes and added examples/clarification/etc. to documentation based on the notes, but having client/user sorting of said notes would have been an absolutely essential tool to speed up the process Plus-one. -Ronabop
Re: [PHP-DOC] About note maintenance; when to delete notes.
On Fri, Feb 24, 2012 at 1:54 PM, Maciek Sokolewicz wrote: > The reason I'm using such "strict" guidelines is simply > to make the manual notes readable. If you look at a page such as > http://www.php.net/manual/en/function.strtotime.php, there are > 100 notes > present. Trying to find something useful to you is simply impossible on such > a page. I disagree. The problem is not that there are too many notes. (That's a bit like complaining the internet has too many pages). The problem on that page is that strtotime isn't documented in such a way as to make the many notes unnecessary. > Trying to clean that page to only leave samples that solve very > common problems or clarify the behaviour of the function is IMO a good > thing. That does often mean removing various code samples of the type "this > might be useful to some people". > > I am wondering what others think, should we try to thin down the stream of > notes and simply delete notes that have little to say about the actual > function or are of relatively little use to the common PHP coder? Or should > we leave as many notes as possible with examples so people can find > *anything* in there? Possibly leading to unwieldy long lists of notes? > > What do YOU think? Feel free to comment / criticise / be constructive ;) Notes, to me, are an indication of what is lacking in the manual. If you want to delete a note, make sure the content/idea/concept has already been put into the documentation somehow. Update the documentation, *then* delete the note. Simply deleting a note adds no value to the project. A page with many notes is a page in need of a re-write, not a note purge. -Ronabop
Re: [PHP-DOC] hotelcallcenter.com now links to you
I can't tell if this is a "humor fail" or not. But if you could kindly link more often to example.com, our associates would greately appreciate and return the favor by linking to php.net to as so increase your leads and revenues, assuring you a more successful business enterprise. ;) On Fri, Jul 15, 2011 at 7:49 PM, wrote: > just trying my best to protect our group here. > that's why PHP growing fast. :) > > > On Sat, Jul 16, 2011 at 10:23 AM, Daniel Brown wrote: >> >> On Fri, Jul 15, 2011 at 21:52, wrote: >> > that's spam. don't click. >> >> Thanks for your report. It's folks like you who really make the >> Internet safer. >> >> -- >> >> Network Infrastructure Manager >> http://www.php.net/ > >
Re: [PHP-DOC] Suggestions about Front End code examples
On Dec 5, 2007, at 5:23 AM, Keryx Web wrote: Hi Today I polluted the internals list with an off topic remark about Front End code quality. I quote myself: [Off topic rant] I am constantly amazed that some PHP-wizards, whose knowledge of back-end development clearly shows in how many ways I must still be considered an newbie, are very unaware about what has been going in on the front end this century, with regards to accessibility, standards, unobtrusive scripting, semantic (X)HTML, CSS-based design, etc. [/rant] Now, things might improve if the manual nudged people in the right direction. I am not thinking about teaching HTML or CSS, but doing the small right things in all examples. E.g. This page: http://docs.php.net/manual/en/introduction.php The HTML in "An introductory example" should have a DOCTYPE. And always a strict version of either HTML 4.01 or XHTML. I will in a separate mail submit text that may improve this page: http://docs.php.net/manual/en/tidy.examples.php Lars: If you "speak" XML, and have a strong, critical, eye for ensuring that documentation is both complete *and* concise, you're more than halfway to becoming one heck of a documentation author for PHP. Have you considered helping out? It's one heck of a resume/ recommendation builder. Some starting points: http://doc.php.net/php/dochowto/ http://doc.php.net/wiki/ --ronabop
Re: [PHP-DOC] Improving the documentation
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 lt 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
Re: [PHP-DOC] [Fwd: PHP install instructions for FreeBSD]
On Sunday, August 31, 2003, at 06:48 AM, Gabor Hojtsy wrote: Anyone motivated to add this to the docs? Would be nice to check first... I have no FreeBSD... Goba From: Greg Magnusson <[EMAIL PROTECTED]> I hereby grant publication privileges to include this procedure, found in the attached file, in the PHP manual found at http://www.php.net. If you choose to publish this procedure, please include my name within the document. FreeBSD conventions, author credit and all -Bop
Re: [PHP-DOC] Notes systems
On Tuesday, August 19, 2003, at 08:45 AM, Mehdi Achour wrote:
Ronald Chmara wrote:
On Sunday, August 17, 2003, at 08:56 AM, Mehdi Achour wrote:
It tends to vary over time. When people are very active, the notes
are well maintained. Sometimes people become less active. From what I
can see, I think the manual is still totally flooded with confusing,
contradictory, and poorly written notes.
As far as "who is allowed to manage a given page of notes", I think
the bare minimum should be
1. Those who know PHP, and the note subject, well.
2. Those who have experience with writing PHP's documentation
(preferably). If notes editors are also writing documentation, *most*
of the good notes can be deleted as they are integrated.
And what about an abusive note ? Do we need to know how work the
domxml extension to delete some non-related note ?
Interesting.
I would say: You *must* know everything about the domxml extension to
*know* if the note is unrelated. If it was abusive and unhelpful,
delete.
I wasn't talking about the skills needed to moderate the notes, but
this can also be discussed. I was objecting for allowing other ppl
(not memebers of the PHP team) to moderate the notes as I've seen that
it was dicussed.
/me checks out the php team list
A good 200+ people. Most of the people *know* their work. If an Oracle
expert starts slamming MySQL , corrections will happen.
I, personally, have not seen a great loss in the notes. Perhaps some
examples would help.
2) Reasons for suppression :
As approached in my first mail, we see from time to time abuses
in the moderation,
Rather than adding to the workload for each note, how about
correcting the actions of the abuser themselves?
You mean posting the note again if it was deleted ? Who will take care
?
If someone wanted to abuse the system:
Everytime a MySQL fanatic posted a message that MySQL can do
transactions...
a PostgreSQL fanatic could delete it
Eventually, php.net would see the cvs churn. I hope
Uhm... HEY! OVER HERE!
Would that be a more effective solution than adding a greater
workload to a simple system?
A smart note, which maybe deserve to be integrated to the manual
lost, without any
understable reason :
"note was deleted from by [EMAIL PROTECTED]"
Why ? did "" read it all ? does he just want to show that
he's "taking care" ?
There are a lot of valid reasons for deleting notes... ;-) If one
cannot *trust* in someone else's competency to manage the notes,
adding a bunch of categories that they "check off" will not fix that
problem. Rather than "abusing" without a reason, they can simply
"abuse" *with* a reason, valid or otherwise.
Abusing with an invalid reason is more critical then abusing with no
reason at all. Having the need to supply a reason will *maybe* make
the abuser think twice before deleting the note.
LOL. Ok, this is cultural.
One more occasion to fit our readers needs is lost here.
some notes disserve to be on the users notes, without being
deleted nor integrated.
Can you provide some examples? I perceive the optimal manual as a
manual without *any* notes. If the manual is good enough, no
additional notes and explanations would ever be needed. So, if a page
*has* notes, that is a sign that more effort should be applied to
improving the documentation... to a point where PHP no longer
requires "external help".
For example, a trick on the mysql_num_rows page showing the use of
COUNT() (mysql function) to get the number of records in a table
instead of doing mysql_num_rows(mysql_query('select * from foo'));
That's about MySql magic, not PHP.
This can not be integrated to the manual (or we'll have to introduce
all the optimization stuff) but is really usefull for newbies (when
I've started PHP/MySQL I was using the bad way =D)
there's a lot of examples of this kind.
That's not about PHP.
A new note is posted :
- if the note should be deleted (deleted, not rejected as
described by the current howto) we do
[snip]
This is missing a large number of "other" reasons for
deleting/rejecting notes, here are some reasons from poking around
notes tonight:
12. Coding-101-notes: Notes that mention that things like "closing
quotes" matter. (Uhm...)
(etc.)
nice shot :)
Delete a few hundred a night. Fun. Real fun. ;-)
-Bop
Ronald Chmara
Ronin Professional Consulting LLC
678-530-9542
"They have computers, and they may have other weapons of mass
destruction ." --Janet Reno
Re: [PHP-DOC] Notes systems
On Tuesday, August 19, 2003, at 03:22 AM, Gabor Hojtsy wrote: As far as "who is allowed to manage a given page of notes", I think the bare minimum should be 1. Those who know PHP, and the note subject, well. 2. Those who have experience with writing PHP's documentation (preferably). If notes editors are also writing documentation, *most* of the good notes can be deleted as they are integrated. Didou tries to propose some system, where notes will be categorized "to be integrated", so they can sooner become part of the manual. How does that make them part of the manual sooner? Are doc editors required to look for those tags? Are note/doc people required to work on those categories first? Just because something is "labeled", does it change anything? My practice when I was editing (a very little number of) notes, I left those needed integration, because I only had time to delete bad ones. If I would be able to mark them "to be integrated", I would have done it. My practice would be that if it *wasn't* deleted, it should be integrated. If it's good enough to have on a manual page, it's good enough to be in the manual. Rather than adding to the workload for each note, how about correcting the actions of the abuser themselves? Erm, what do you mean? I am "ronabop". Every note I delete is marked with that name. If I am deleting thousands of notes, out of a grudge, anger, malice, hatred Am *I* the problem, or is the notes system? If I am behaving poorly, should we mistrust *all* notes editors or just me? Rather than making each editor do more work, why not ban my actions? One more occasion to fit our readers needs is lost here. some notes disserve to be on the users notes, without being deleted nor integrated. Can you provide some examples? I perceive the optimal manual as a manual without *any* notes. If the manual is good enough, no additional notes and explanations would ever be needed. So, if a page *has* notes, that is a sign that more effort should be applied to improving the documentation... to a point where PHP no longer requires "external help". I think there are probably many notes, which deserve to be there. There are some notes actually submitted by manual authors, because they thought that it would not fit into the manual, but rather as a note. There are special things, like how to fix some bug affecting PHP in Apache 2.x, and the like. These are too specific to get into the manual, while they are important, and actual stuff. I think PHP and apache 2.x versions is a bad example. I think it belongs *not* as a note, but as a web page about PHP and apache 2.x. Maybe apache 2.X will be a failed project, but, until then, why should it *not* be a manual page? Our users are mostly convinced that the user notes often contain valuable information (more often than crap). We get requests all the time to integrate them in the downloadable versions. I had created the special CHM version, and the feedback I received always pointed to the great inclusion of the user notes This may be an indication that the manual is weak at many places, yes. But it is also an indication IMHO that user notes have their own place. I don't think that this means the notes are "weak", I think it means that the manual is weak. Ronald Chmara Ronin Professional Consulting LLC 678-530-9542 "Shall we play a game?" --Joshua
Re: [PHP-DOC] Notes systems
e bad, only one note
is needed to ask for corrections to the docs. Having 15 notes will not
get it fixed any faster.
5. Old notes that do not relate to old PHP versions, but things like
archaic web browser versions ("To fix a problem with IE5...").
6. Notes about problems that are *so* unrelated to the page as to be
meaningless (Example: A note on a file upload page about a buggy
ethernet card/driver causing upload problems.)
7. Didn't RTFM: Notes which say (or imply) that the user didn't
actually read the page (such as notes to set important configuration
directives... which are mentioned on the page).
8. Slashdot-style Opinion notes: For example, people posting how they
*think* a function should work, how OO "should" work in PHP, etc.
9. Pointless nit-picking notes: For example, 3-15 notes arguing over
"whether or not /r/n is RFC822 compliant".
10. Repeat notes: For example, quoting an entire note and then noting
that it helped someone.
11. Reworded-bug-report notes: A clever way of getting around some past
or present PHP bug is *still* a bug report. The solution is fixing PHP.
12. Coding-101-notes: Notes that mention that things like "closing
quotes" matter. (Uhm...)
(etc.)
I'm sure we could create labels for all of these (or apply existing
ones), but to what end? If the end product is a good manual, annotated
and then improved as needed, how will it help reach that goal if each
note submission/rejection/deletion/integration requires more work?
Especially since the manual is still filled with notes that need to be
integrated, or removed?
Ronald Chmara
Ronin Professional Consulting LLC
678-530-9542
"The question of whether a computer can think is no more interesting
than the question of whether a submarine can swim." ---Dijkstra
--
PHP Documentation Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[PHP-DOC] Re: [PHP-NOTES] Re: [PHP-DOC] Re: Notes Status, 9952 total
On Saturday, August 9, 2003, at 08:45 PM, Mehdi Achour wrote: BTW Goba, can we make things move for the notes maintenance ? Two things : 2 - The notes system From the same URL, topic "3. User note handling" When deleting : - outdated : for example, a note helping to configure some library with PHP 3.X, a note using a function that is no more part of PHP. - replying : the note is a reply to another note asking for help. The original note should be hunted down and rejected (as stated in the HOWTO) So should the reply, IMNSHO. - bogus : for example, a note giving an example for a mysql_* function on a mssql_* function page. - trash : spam, bad words, an _old_ (more than 6 months is a good limit) note asking for help, a non-english note, a note that should be rejected but have a wrong email address .. - duplicated : there's already a note saying the same thing, differently. If there's a lot of duplicated entries stating the same thing, we should think about integrating the note in the manual - added : the note content was added to the manual. We can even send a mail to the note submitter, giving him a link to the updated CVS file and thanking him for his add-on. When rejecting : - support : a note asking for help Uhm, see above? Here's how I think of the notes: Unless it helps *me* somehow, someday, it doesn't belong. -Bop Ronald Chmara, Ronin Professional Consulting LLC 520-326-6109, [EMAIL PROTECTED] "A strange game. The only winning move is not to play. How about a nice game of chess?" --Joshua -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] Re: Notes Status, 9952 total
On Saturday, August 9, 2003, at 03:16 PM, Mehdi Achour wrote: Hi, Just FYI, some statistics about the notes moderatores are there : http://didou.keliglia.com/notes_stats.html It's *not* official and maybe false Whoa. Many months of near-inactivity and I'm still way up there. Looking at didou's work, he's catching up fast. :-) Generally, when I "note-slammed" a page: 1. I go through each note on the page, while I have the xml doc open. 2. If I can add a line or two of clarification, or enhance an example based on a note, I delete the note and add to the docs. I had found that an amazing amount of note content can be summarized in just a few more lines of documentation, or an additional line (or three) of example code. -Bop Ronald Chmara Ronin Professional Consulting LLC "Never send a human to do a machine's job." --Agent Smith, "The Matrix" -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP-DOC] Re: PHP documentation authors / editors and license
On Sunday, February 2, 2003, at 03:13 AM, Zak Greant wrote: Heh. The content is already in docbook and the user notes are mostly useless already. ;) *wakes from a long slumber* Depends on coding style (the notes), doesn't it? I used to bitch about PHP2->3 migrations, now I have 3->4, and 4->5(?). Revenue for me, but... Seriously, of course it is better that we use what we have and just change to a better license. However, we do have options - this being one of them. :) For the PHP ER, I spent a *little* bit of time revising old docs. It was a bit sad, seeing how many simple protos were... to put it gently, not currently accurate. It (the PHP ER work) knocked me out of docs for a while. Somewhere around here I have information to get paid for it... I never sent it in. Heh. For proper tribute, multiple CVS dumps should allow for *all* of the applicable authors to be listed. It sounds a bit like the BSD license, but what is the cost of 2 (or even 12) pages of 6 point text in a thousand page manual? About nothing. Web costs? Even less. Give the chapter-slaves their credit, the editor folks their credit, the one brilliant example their creditetc. Or, switch from an old über-editor-batch to a "new" über-editor-batch... hmm. -Ronabop -- PHP Documentation Mailing List (http://www.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php
