Paul M. Jones

One of the big gripes I have about most public PHP code is the dearth of decent documentation. I do not mean inline comments (which are just as necessary), I do not mean comments that have been turned into web pages with phpDocumentor (which is often quite nice), I mean from-scratch written-for-the-newbie plain prose documentation on what to do, how to do it, why to do it like that, and (most especially) what the shortcomings and workarounds are.

When a new user asks about documentation, or complains about the state of existing documentation, here are the most common responses I see:

• "I'm too busy to write documentation."
• "There's already documentation, read the inline comments."
• "Read the mailing list." (Without a direct link to a relevant email on the list.)
• "This is open source, write it yourself and contribute it."

Documentation of public PHP code is the responsibility of the original coder. Not the users, not some third-party angel, not "the community" ... the original coder.

It's not hard. You don't have to do the whole set of docs at one time; at the worst, put up a wiki so you can edit them as you go. (A great side-benefit of a wiki is that your users can also mark up the docs to tell you what's most important to them. Just get something out there, in public, and add to it regularly as emailed questions come in.)

More on this later. Flame away in the comments.

Update:

With regard to Nelson (see the comments): I'm talking mostly about userland code written in PHP, generally classes or applications, not the functions of PHP itself. PEAR in particular has a serious issue with this, because they insist that all official documentation be in DocBook format. I'll talk more about that later, too, likely in a different post.

And with regard to inline comments, and reading the code itself: great if you're trying to troubleshoot. Pretty bad as your first introduction to the class.

And if you get the same question over and over about your project, then put that question (and its answer!) in a prominent place. If users keep asking that question, you have failed to properly or usefully document it. You need to change your documentation, not berate your users, becuase your documentation is being proved not-useful repeatedly. Even if you don't change your docs, be patient and answer with a link the solution (and if you don't have a link to the solution, then you lose again -- make one!)

And before we talk about the pot-kettle-black thing, take a look at wiki.ciaweb.net -- all my stuff is documented thoroughly, by hand, with two exceptions: the very new Savant2, and the still-alpha YaWiki (and I'm writing the docs for that as an International PHP Magazine article).

For my first nine hours of tuition in the MBA program at the University of Memphis Fogelman College of Business, I paid $2794. Ouch.

And that doesn't include books.

I simply must look in to financial aid.

Belmont Club writes about the rise of internet media (bloggers) over traditional big media gatekeepers:

So when the Swiftvets story shouldered its way into the public consciousness despite the best efforts of the "gatekeepers" to consign it to oblivion, it posed an existential challenge to the news foundries. For where one could come, more would follow. The Mainstream Media responded to accusations by Swiftvets that Kerry had misrepresented his combat record in Vietnam by creating their own alternative news object, whose methods were restricted to OutrageAgainstBush( )  and SympathyForKerry( ), with read only properties Responsible and Respectable. They could no longer block the data, but they could still transform it.

Kind of a funny analogy. :-)

So I'm out ego-surfing for reviews of my Savant template system, and I find this from Norbert Mocsnik; he says he tried other template engines such as Smarty and Flexy, and then...

Conclusion: whatever template engine I've tried (it probably helped me a lot in developing applications faster BUT) all the time, I mean every time there were things that I couldn't do with them.

So I switched back to Savant. Simple. Nothing to learn. Nothing that you can't do. Pure PHP. I recommend it for y'all. Give it a try. (it has drawbacks also.. if you want your users to be able to edit the templates, it's probably not a good idea to let them enter arbitrary php function calls.. there may be other things.. feel free to comment).

I love good press. :-)

Norbert makes a great point about the Savant 1.x series: all templates must be written in pure PHP, which sucks if you want to give untrusted users access to your template code.

Solution: try Savant2. :-) Savant2 has optional support for any custom compiler object you wish to write; just pass it into the Savant2 object using setCompiler() and Savant2 will use that object to compile the template source into PHP for you. (Of course, you still have to write the compiler yourself, which has benefits and drawbacks of its own -- but one major benefit will be that you can replace one compiler with another and still use the same template system API.)

While I'm shamelessly plugging my own work ;-) I'll mention that Savant2 is no longer dependent on PEAR. It has a customizable error system that can use PEAR_Error, PEAR_ErrorStack, or any other error handling system you want to plug into it. Savant2 even has suppoort for streams as template sources.

The only bad thing about Savant 2.x is that the documentation is not complete. You can see the work-in-progress docs here.

UPDATE (2004-11-18): Documentation has been complete for several weeks now; you can view it at the Savant web site.

Here we have Rasmus talking about PHP.

Q: How will PEAR fit into the scheme of things with PHP?

A: I think it's vital. We need a better way of installing applications. The PEAR installer is needed at this point, as it is hard to download any PHP application and just make it work. If we can get a single unified installer so you can see PEAR and just make it work, that would be cool.

I have a few packages in PEAR, and depend on even more, so it's nice to see the project getting good press.

Reading planet-php.net today, there's some talk about multi-byte encodings in PHP for internationalized text handling. This is one of the issues I have to deal with in the Text_Wiki project (say with a Hebrew wiki).

John Lim points out in this post that there are already good multibyte functions in PHP. This is fantastic news!

The only downside is that you need to compile them into your PHP installation explicitly (they're not on by default). Also, in order to use them effectively, you need to either (1) code for multibyte function to begin with, say mb_substr() instead of substr(), or (2) (and this is this cool one) turn on multibyte overloading so that the multibyte function is used when you call a related single-byte function -- this means you don't need to re-code your app, just recompile PHP and change up your php.ini.

I love this stuff. :-)

Text_Wiki is an object-oriented parsing engine for wiki markup. The change notes for this release are:

* for deflist, must now use ": " (colon-space) at beginning and " : " (space-colon-space) to separate term from def; this it becuase URLs as terms were breaking the rule

* fixed bug 2095 so that CSS is now honored in deflist rule (thanks for the patch, glamm at a-s-i dot com)

Download at http://pear.php.net/Text_Wiki/.

My sister Alaina is in town; she arrived yesterday afternoon and immdiately fell in love with Wendy, my new dog. Alaina and I went out to eat and caught up on each other's lives. She's moving from Indianapolis IN to Columus OH in a month or so.

Here's the funny thing: I'm not a very religious man any more, you could call me more an agnostic or a Joseph-Campbellian. I like to think, as Franklin did, that there is a Providence that leads us toward good ends. Providence appears to have led me to adopt Wendy so that Alaina could take her home. I could be very happy with that end. :-)

Last week, my neighbor Phyllis from down the street was talking about a dog she found at the corner of Riverdale and Quince. Phyllis has four cats, and they were terrified of the new dog, so she couldn't keep it. At the same time, she didn't want to just "give the dog away" -- instead, she wanted to adopt it out to a good home. I told her to bring the dog by to my house Monday evening; while I wasn't going to take another dog in, I have another friend (Libby) who is a dog fanatic and who would know of any good homes in the area.

On Monday, the new dog arrived in my backyard for play-time and looking-over. A good natured creature, mostly lab but with a little chow, perphaps some dachshund (long nose), about 25 pounds with a short golden brown coat. 6-9 months old, some minor tooth problems, sweet as could be.

So I took her in. :-) I've started calling her Wendy; it's not a Peter Pan reference, although I could work one up easily enough. "Wendy" just sounds right for her. She and Zoe (my first dog) are quickly becoming used to each other.

(YaWiki is a wiki-based collaborative documentation system.)

The change notes are:

* Fixed break in area_pages.php where a call to the map did not specify which area to use

* Fixed break in yawiki.class.php method _buildMap() to check isset() on the title for a page

Download from http://yawiki.com/.