This post originated from an RSS feed registered with Python Buzz
by Ben Last.
Original Post: Documentation Available Via Prayer
Feed Title: The Law Of Unintended Consequences
Feed URL: http://benlast.livejournal.com/data/rss
Feed Description: The Law Of Unintended Consequences
Of a Monday morning, when the giant dung-beetle that pushes the sun is busy crawling up the dome of the sky, I like to click my way through a whole bunch of RSS feeds and see what scuttles out. Following links brought me to the PyPerSyst object database; I like object databases, so I had a read, and came across this gem of a line: "PyPerSyst Architecture: This section is horribly out of date, and will be updated soon. In the mean time, refer to the source code." The page is in a Wiki, marked as "last modified 2003-10-02 23:39:13". I like open source. I like the idea, I like having access to cool stuff for free, I like the fact that I can fix and extend things in a way that goes back out to other people doing the same things as me. But sometimes the sharp, unpolished corners of the open source culture can scratch, as in code that evolves and becomes more complex, more fitted to certain niche uses whilst the documentation fossilises under the weight of time.
The SlashDot response to this is to say "send patches, not complaints"; I see this as kinda-sorta derived from that old proverb Never look a gift horse in the mouth. My response to that is to muse on the subject of responsibility and completeness; if you donate something to others, how much are you beholden to support them in its use? Would you, to conjure up an analogous situation, donate computers to a school but then not invest the time to get them set up and working? Okay, that's a somewhat extreme example (but sparked by stories in the press over the last few months), but the assuredly blunt point I'm trying to make is that when you give something back to a community you value, you need to give back a thing that is complete unto itself. With PyPerSyst, Patrick O'Brien deserves kudos for creating something clever, elegant and useful at the very least, and it deserves to be better supported.
Zope's an interesting thing to look at here: the documentation is always somewhat out of date, but it does exist, and it features a comment system that lets readers add their own pointers and counter-examples. The Wiki and the website are full of HOWTOs, the mailing lists full of discussion. There is an understanding that the way to help people learn a complex system is not to direct them to the source (though the fact that it's always there for reference is invaluable) but to provide them with the surrounding and supporting buttresses that hold up the walls of the grand cathedral of code and help it soar skywards. I've been critical of Zope on here, but it does have its good points, and that's one of them.
I'll finish off the act of sticking my neck out and labelling myself as a troublemaker (but nice Smeagol always helps!) by piling up a small wall of protective sandbags in the form of this story. Back in the mists of ancient time, when the only MS-based webserver with DLL support was Purveyor, before even IIS 1.0 was released, I built a website that ran on a mix of C and Java[1]. There was no J2EE then and no servelets, so I came up with a way to get the webserver to run Java classes as CGI, and released it as open source (link goes only to a notice about it, the package is long dead). Before I did that, I took a day off to write enough documentation to support it. This was from pure and unadulterated self-interest - I didn't want my email to be filled with support requests. So from selfish motives I did, once, practise what I preach.
[1] It still is running that same code; an object lesson in how a workaround solution tends to be kept alive indefinitely. Makes me shudder, though I'm quite proud that it's lasted so long.
Previous Topic
