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