Document Your Project Already!

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

Buzz! All wrong answers, thank you for playing, we have lovely parting gifts for you.

Documentation of public PHP code is the responsibilty 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, becuase 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 quesiton, 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 your codebase, all while keeping it running the whole time.

16 thoughts on “Document Your Project Already!

  1. While this is true of many PEAR and PECL packages, the majority of PHP and its “internal” extensions is quite well documented. The online manual is probably one of the very best references for any programming language ever – useful and practical. Now, if you’re talking about OSS in general, I’d agree with you (yes, the big projects are usually well documented, but smaller, 1-or-2-developers projects are sometimes too difficult to reverse-document from raw code for them to be workable.)

  2. On second thoughts; I’ve just remembered several painful hours of trying to get sensible information out of MS VB documentation some years back… it always mentioned dragging-and-dropping controls though.

    And .NET docs are so entangled in abstraction layers that the whole thing feels like it requires two PhDs in advanced post-parallel subliminar computing theory before you understand how to create a snippet of XML.

    No, scrap what I said before; OSS docs (or lack of) are great! =)

  3. Wikis rock for documentation. While I dont agree its the job of the original author to actually write the documentation I still think that documentation is very important. Wiki’s effectively take the pain away by making the process simple, collaborative and flexible. We have been ususing yawiki for a while now to generate our documentation. We have a set of custom wiki rules that even allow is to export to OpenOffice flatfile format including table of contents, remote images and tables. With a little bit of hand cleaning we can produce a nice PDF from our wiki that can easily compete with any documentation.

  4. RE: Document Your Project Already!
    Paul M. Jones has written a blog post in which he complains about the lack of documentation in public PHP code. I agree that the low standard of documentation is bad but I believe that he misses the most important point:

    It is not fun to write docum…

  5. An idea I’ve got is to integrate Unit Tests and Examples.

    There should be a kind of tests, that makes itself into practical example that can be compiled in a doc format.

    What do you think ?

  6. Hi, Lukas —

    Thanks for the good YaWiki buzz. ๐Ÿ™‚

    You wrote that you don’t think it’s the original author’s responsibility to actually write the documentation. Other than a formal documentation person or team, neither of which generally exist in open-source userland public PHP projects, whose responsibility would you say it is?

  7. DocBook requirement is a *huge* roadblock to docs in PEAR. I’m not sure what great advantage it provides, besides perhaps possibility for CHM format (how many people care if PEAR docs can be viewed in CHM?).

    I’m certainly not immune from the laziness that keeps things from being documented, but for my projects I have found that using XHTML docs makes it 1) extremely easy for me to update docs, and 2) makes it extremely easy for others to contribute docs. (It’s basically the XHTML+XSLT solution that Binarycloud uses.) With XSLT and other 3rd party tools like htmldoc, it’s possible (even easy) to create other formats (e.g. PDF).

    I agree that it is the responsibility of the original developer, but I also think it makes sense to lower the cost of entry for writing documentation.

  8. Documentation should be written by those who can. Those include the original author as well as anyone else who has learned something about a piece of code. Obviously some things will be hard to figure out for all but the original author. However I have answered countless questions on LiveUser yet nobody feels inclined to write up a coherent piece based on my answer into our LiveUser wiki. I would say users need to get off their asses more and do what they can do themselves. I would be much more willing to fill in the blanks than writing the thing from scratch, afterall my talents lie elsewhere.

  9. Documentation should be written by those who can. Those include the original author as well as anyone else who has learned something about a piece of code.

    That skips the question of whose responsibility is. I maintain that it is the responsibility of the author. If the wuthar can get other people to do it for him wonderful; if those people then do not produce docs, the author failed to fulfill his responsibility.

    The author writes a program, the author decides the world should see the program, the author publishes the program. Then, when a user asks how to use the program, the author says “figure it out yourself” (or worse). If the author receives multiple questions about the same topic but cannot be bothered to publish the answers as documentation, somehow it is because the user did not “get off his ass”. This does not scan. The one person in the best position to write useful documentation about the program is the author; nobody else “feels inclined to contribute” because they’re spending all their time trying to figure out the program — because there is no documentation.

  10. You can’t say that it’s someone’s responsibility to write documentation. Well, of course in places like PEAR etc you can have rules, but I understood your original blog post to mean public PHP code in general not just something specific like PEAR.

    There can’t really be a law that if you publish code to the public you have to also write proper documentation for it ๐Ÿ˜‰

    Of course it would be good if there is documentation and yes, the original author is in a good position to write it because of the intimate knowledge of the code. However, my opinion is that code without documentation is better than no code at all.

    If just one single person finds the code, figures out how to use it, and use it in some way. It’s useful to publish the code. If there were 50 persons who found the code but couldn’t figure out how to use it due to the lack of documentation they are not worse off compared to if the code wouldn’t have been published at all.

  11. you seem to overlook the fact that the original author already wrote the code in the first place. Now its time for the other people who get to use this code freely to give to the author in order to make the entire publication worthwhile to the original author. If publishing code only means you have to do stuff you otherwise wouldnt have to do and you get nothing in return then there is a flaw in the system.

    If I would place any responsibility I would surely place it with the users, especially those who have received answers from the original author when they asked questions.

  12. On the docbook front, the problem IMO is there’s no free WYSIWYG docbook editors out there (at least that I’ve found and I’ve looked). Editing docbook by hand is a pain, even if you’ve got a validating tool.

    LaTex _does_ have WYSIWYG editors out there, which makes me wonder if it might be a better place to start. There do seem to be ways to convert LaTex to docbook e.g. TeX4ht – looks like alot of work is needed to configure it but once done, could make the config available via the PEAR website.

  13. People,

    there is NO rule stipulating that PEAR documentation has to be written in DocBook XML. If people e.g. want to write documentation for a package in a Wiki, a link to this Wiki will be added to the PEAR manual.

  14. Hi, Martin — This is true. In fact, David Costa has made available some wonderful work for making DocBook skeletons with links to external documentation. Check it out here.

  15. A technique I have found extremely useful on OS projects is TDD. No not test driven development, but “Tutorial Driven Design”. Write the tutorial first. You end up with more usable code that way too :).

    yours, Marcus

Leave a Reply

Your email address will not be published. Required fields are marked *