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).

Are you stuck with a legacy PHP application? You should buy my book because it gives you a step-by-step guide to improving you codebase, all while keeping it running the whole time.