Paul M. Jones

See this Educause article about wikis; hat tip to Many2Many for the link.

Indeed, an instructor could structure and regulate interaction to such an extent that the wiki is effectively transformed into a stripped-down course management system. But doing so risks diluting the special qualities that make wikis worth using in the first place, with the result being, in the words of Heather James, "pumped-up PowerPoint." James has described the experience of using wikis in her teaching as her "brilliant failure." She regrets that she "changed the tool, but did not change the practice," and failed to account for the "great potential in this tool to be completely disruptive (in a good way) to the classroom setting." With the benefit of hindsight, she concludes that for wikis to fulfill their promise, "the participants need to be in control of the content"”you have to give it over fully."26 This process involves not just adjusting the technical configuration and delivery; it involves challenging the social norms and practices of the course as well.

Norbert Mocsnik has some thoughts on form building/processing. Check it out, see what you think.

I have some ideas of my own, and I'll post them either as updates to this post or as a separate entry.

Cox & Forkum: That Day

With the caveat that I think Bush is doing only one thing right (i.e., his prosecution of the war against Islamo-Fascism), I found this piece from David Gelernter quite refreshing.

THE WAR IN IRAQ is dual-purpose, like most American wars. Take the Civil War. At the beginning, the North fought mainly for pragmatic reasons. No nation can tolerate treason, or allow itself to be ripped to bits or auctioned off piece-wise by malcontents. Midwesterners couldn't allow the Mississippi to fall into foreign hands; they needed their outlet to the sea. And so on. Slavery was overshadowed. But as the war continued, slavery emerged as the issue, and the war's character changed.

The Iraq war started as a fight to knock out a regime that invaded its neighbors, murdered its domestic enemies with poison gas, subsidized terrorism, and flouted the international community. Obviously such a regime was dangerous to American interests. But as the war continued and we confronted Saddam's gruesome tyranny face to face, the moral issue grew more important, as emancipation did in the Civil War. For years the Iraqi people had been screaming, in effect: "Oh, my God. Please help me! Please help me! I'm dying!" How could America have answered, "We don't want to get involved"? We are the biggest kid on the playground. If we won't help, who will?

There's quite a lot; read the whole thing.

Gelernter knows personally about terrorism; a package from the Unabomber blew off his hand.

UPDATE: Forgot the hat-tip to Photon Courier.

Belmont Club has a good post about the options Russia had available to it during the recent terrorist attack on a school in Beslan. They have this to say about America's prosecution of World War IV:

America's unmatched power allowed President Bush to select the most humane course of war available. No European power, nor all of them put together, could have embarked on such a precise campaign for lack of means. It was a rich man's strategy, a guerre de luxe.

Read the whole thing; it's short and to-the-point.

Yawp 1.0.3 is online now. This is a bugfix release; I was using "@include" instead of "include" for hook scripts, which effectively turns off error reporting inside those hook scripts. Yawp uses just "include" now; sorry for any trouble this may have caused when troubleshooting.

At the same time, this uncovered a bug inside PEAR Benchmark_Timer; you can read more about that here.

I begin taking classes tonight. I had wanted to start with something, anything, other than the information systems course, becuase that's all I've been doing for five years. But I wanted desperately to take the Research Methodology course from Emin Babakus, who was my boss for a time when I worked at FCBE, and everything else conflicted with that. So information systems it is.

Research Methodology is Tue/Thu, 5:30 to 6:55 pm.

Management Science and Decision Technology is Tue, 7:10 to 10:10 pm.

Information Systems in Organizations is Wed, 7:10 to 10:10 pm.

My God, on Tuesdays I'm in for four and a half hours of classes after working all day. What the hell was I thinking?

Research Methodology had better be worth it. ;-)

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.

For those of us lucky enough to edit text on Mac OS X, Bare Bones Software has recently released BBEdit 8.0. Very nice improvements.

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.