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.

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.

2 thoughts on “Document Your Project Already! (Part 3)

  1. Well I never thought I would see political thought so neatly expressed in the realm of software development.

    It boils down to your take on responsibility. You say the commnuity has no responsibility to the individual. Lukas says the individual has no responsibility to the community.

    Should individuals simply contribute as they see fit. Or, do members of a community have a responsibility to the community because of the benefits they derive from being a member?

    You see the author’s compensation as, “the joy of having other people use his work.” Lukas sees author’s compensation as the benefits of being a member of the community.

    You want individual excellence. Lukas wants community excellence.

    Community excellence get better overall documentation, but is harder to achieve. Individual excellence produces some rich documentation, but more poor documentation.

    From a license point of view you are right:

    What exactly do the software users owe the software author? Nothing other than to adhere to the terms of the license.

    But you omit your fundamental misunderstanding of the relationship between the open-source software author and the people who use the freely-given software:

    What exactly does the software author owe the software users? Nothing other than to adhere to the terms of the license.

  2. I tend to agree with Paul; it’s the responsibility of the developer to document code, but my main reasoning is mainly pragmatic:

    If you write code and don’t document it fewer people will use it.

    Running an open-source project is about more than coding. If you are unable to do anything but crank out sourcecode, then you should simply be a developer on a project, and not the project manager.

    I completely understand open-source work to be about giving to the community, and expecting little or nothing in return. I run open-source projects because I like to code and because I like the experience of running projects, managing releases, etc. But I do also do it out of a certain sense of responsibility. I use countless open-source projects every day, and I don’t feel any real responsibility (aside from license) to the projects that I use. When I discover bugs, I report them. When bugs don’t get fixed, I just move on and find a better package; I don’t think it’s not my responsibility to make the package better (and certainly not to write documentation for something I didn’t create). But when I decide to write my own tools, I do feel it is my responsibility to give back as much as I can to the community from which I’ve certainly taken so much.

    In short, to me, writing open-source software is about enjoying software design and project management and repaying a low-pressure debt incurred over years of using other open-source software. And in the end, it’s quite simply a fact that if you don’t document your project few people will consider using it.

    -Hans

Leave a Reply

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