Monthly Archives: August 2004

Document Your Project Already! (Part 3)

This is the third in an unintentional series about documentation and open-source PHP projects. See part 1, part 2.

In the interest of pithiness, I will excerpt and summarize the commentary and argument I wish to present.

Lukas: While I dont agree its the job of the original author to actually write the documentation I still think that documentation is very important.

Me: 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?

Lukas: 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. … 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.

Me: That skips the question of whose responsibility is. I maintain that it is the responsibility of the author.

Lukas: 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.

(To quote Saturday Night Live Jeopardy, “Simply stunning.”)

Here we have the heart of the matter: a fundamental misunderstanding of the relationship between the open-source software author and the people who use the freely-given software.

What exactly do the software users owe the software author? Nothing other than to adhere to the terms of the license. Users may wish to express their good will in many ways, but they do not owe the author anything in addition to the licensing agreement.

This means the users are under no obligation to provide patches, report bugs, suggest improvements, or even say they like your work. They may wish to do so; if users are sufficiently self-interested, or if the author has generated enough good will, they are almost certain to want to help. But they are not obligated to do so; while they can help to improve the software, they are not responsible for its maintenance.

Certainly positive feedback is in the self-interest of the user, as good words (and PayPal tips! ;-) have a wonderfully stimulating effect on the author’s willingness to continue publishing his work. But it is not an obligation in any sense other than “it is encouraged and welcomed by the author.”

Lukas believes the users owe him for his work, that he deserves some form of compensation. I think he does deserve compensation, but not the in way he thinks.

An open-source software author’s compensation is this: the joy of having other people use his work. In short, the author’s compensation is “the joy of giving.” In the same way that good deeds are their own reward, publishing your software open-source is its own compensation.

Anything more than the joy of giving is extra, and not to be expected. Perhaps if the software is well-received, the author may have additional compensation in the form of fame (or infamy ;-). If the software is really popular, he may receive contributions in the form of reports, patches, cash, or even documentation. But it is not owed to the author; it is a representation of the good will generated by his act of giving freely, which has prompted others also to give freely. Users perform no wrong by not contributing, but they perform additional good when they do.

Lukas said, “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.” I would argue that is is already worthwhile to the original author. The author wrote it for his own purposes; certainly he is not writing it so he can not-use it.

And finally, Lukas said, “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.” There is no flaw in the system; the flaw is in Lukas’ misunderstanding of the system. A more accurate understanding is: “The reward for good work is more work.”

Once you have closed the last “?>” PHP tag of your code, you have completed the first part of your public open-source project; the next part includes (among other things) writing the documentation for it. Nobody else is obligated to do it for you — and telling your users to “get off their asses” is not going to help generate the good will you will need for them to get involved in your project.

Document Your Project Already! (Part 2)

Joakim Andersson has some honest and forthright responses to my earlier post where I state that “Documentation of code is the responsibility of the original coder.” I want to take his points one by one; they deserve special attention because Joakim has been very clear and direct about his position, and I think they serve as an excellent sounding board.

The following quotes are from Joakim’s comment on my blog post:

You can’t say that it’s someone’s responsibility to write documentation.
…
There can’t really be a law that if you publish code to the public you have to also write proper documentation for it ;)

I agree, although I think Joakim misunderstands my position. I say this not so much as a command (“You must document!”) as a statement of expectation (“If there is to be documentation, the coder must understand that he is the one responsible for creating it.”) I say this because far too many coders misunderstand the nature of their relationship to their user base. (More on that in Part 3 of “Document Your Project Already!”)

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.

I agree on both these points. Code with no docs is more useful than no code; docs with no code is planning, not code. However, with documentation, more people will be able to get started with and make use of the code. In turn, users will be better able and more willing to contribute back into the code. This serves both the author and the userbase.

In addition, the very act of writing documentation will make your code better. When you start to have to explain, in plain terms, what you have done and why, you will realize all the little inconsistencies in your API, all the little assumptions you have about the code use, and many other little things that all add up to a higher quality piece of work.

Documentation, in short, is not only for the user’s purposes; it is in the interest of the coder for his own purposes.


Joakim also wrote a blog entry of his own about my post. I now quote from there:

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

Joakim, I promise you: I have not missed that point. Documentation is hard work; a different kind of hard work than writing code, to be sure, but hard work just the same.

As soon as the fun turns into a must, it’s not fun anymore and the probability of it getting done goes towards zero. As soon as I start to feel that I have to write documentation, I’m basically doomed to fail with it.

Paul also states that “I’m too busy to write documentation.” is not a valid excuse. However, it’s not as simple as that. Take a lack of time and combine it with a lack of fun to write documentation and you have totalt disaster.

Again, I understand this completely. However, my point (as stated above) is not “You must document!” but that if documentation is to exist, the original coder is the one responsible for it. If other users create it, wonderful; if somebody writes a book about your code, great; but if nobody steps up to write documentation, the coder has no cause for complaint, because the original coder is the one person responsible for making it happen, nobody else.

I am not saying that Joakim is complaining, because he is not. His position is honorable and honest:

I’m the author of The Ismo PHP Framework and as can be seen from its documentation page the documentation is next to nonexistent.

The food on my table I earn by working 40-50 hours per weeks at my day job (not PHP-related in any way). Subtract some more hours for going to the gym, going running, meeting friends, playing with the cats, etc. What’s left is like 5 hours / week tops which I can spend on my spare-time projects.

Notice that Joakim does not blame his users. He knows there are no docs, he is unhappy about it, but at the same time is not motivated to write them. With any luck, Ismo users will want to contribute, but until a certain critical mass of users exist, there won’t be enough people with enough knowledge to write useful content on the Ismo wiki.

Given a couple of hours in a week, do I rather spend them enhancing the AOP (Aspect-Oriented Programming) support in Ismo which is fun, challenging, and very interesting. Or do I spend the hours writing documentation?

I think the answer is easy and one reason why open-source projects often lack decent documentation.

The answer is easy; it depends on what you want. If (“you want more people to find Ismo easy to use and get started with”) then (“you will spend your time where your sentiment is and write documentation”). Any other answer says to the world that going on to the next bit of code is more important to you than making the previous bit of code more approachable and usable.

We just have to find a remedy. Using a wiki is a step in the right direction, but it’s not the magic solution.

I agree. To quote Fred Brooks, author of The Mythical Man Month, “There is no silver bullet.” There is no remedy other than discipline and professionalism: difficult though it may be, express your pride in your high-quality work by writing documentation for it. Your users will benefit from it, and so will you.

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

Savant: Good Words from Norbert

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.

Rasmus Mentions PEAR

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.

Multibyte Characters and Wikis

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 0.21.0 Released

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

YaWiki 0.17.2 Released

(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/.

Yawp 1.0.2 released

The change log is:

* changed error_reporting() calls to ini_set() calls, for some reason the new error reporting level is not always honored on some systems

* fixed a bug in parseConfLines() from 1.0.1 that would prevent multiple groups with the same name (e.g., [Log])

* fixed a bug in start() when setting up the Var_Dump object; now properly sets the display_mode option when [Var_Dump] group has no elements

Download from http://phpyawp.com/.