Open Source And Documentation

From LinuxPerceptionProblems:

The concentration on source in open source is strength and a weakness. Compare how tidily you can build a web application with J2EE (with servlets, jsp, beans and ejb all working together), or under the Microsoft architecture (ASP and IIS filters calling ActiveX objects). Both systems have some kind of overall strategy. Some people in the Linux world actually like using PHP and Perl. Where's the component architecture? Why can't people call perl packages from PHP? Why are both PHP and Perl a mess? (They both seem to have overlapping, incompatible features. Every tool or package seems to be competing of features with many other packages.) PHP for example is a pretty dreadful tool for building any sort of complex web application, and unlike JSP and ASP there's no component infrastructure you can use to easily call components that encapsulate business logic. Actually trying to sketch anything in UML is almost taboo in the opensource culture.

If I see any more written about typeglobs and "blessed thingies" written by Wall or Christiansen, I think I'll scream. Using the word "thingy" in a technical book isn't funny - it is unprofessional. It doesn't make up for not being clear and concise. Language designers and technical authors should have less laziness, impatience and hubris than programmers. Why can't they, just occasionally impose some restrictions. Anybody think that using the same identifier in the same code block for different things is a good idea? (e.g. $foo and @foo being different?) Do they really have to indulge every bad idea with an implementation? Sometimes, for sanity's sake there should only be one way to do it.

I've recently come across the documentation for POE - and it looks like a caricature of everything I can't stand about perl documentation. Here's a real example:

What is POE? POE is a giant ball of kinetic energy and Computer Science buzzwords wrapped in a very strange and wonderful culture. POE is a MUD engine gone awry into some sort of wacked out Disney land of event driven network niftiness. POE is that which keeps many minds from wandering the streets in search of branes to eat. Ok. None of that means anything to anyone. Maybe I should start on a much simpler level, eh?

POE is:

* a perl module Geesh, I started off REALLY simple didnt I? * written in Object Oriented Perl5 Modules are good. OOP is good. * compatible with perl 5.004_05 and up Will most likely run on most annoying web hosting services out there. * a pseudothreading application kernel Huh? The short version is that perl programs can pretend to be threaded on a non-threaded perl with POE. POE is essentially a cooperative task scheduler at heart. Tasks are bundles of event handlers that look a lot like state machines. Several of these carefully constructed state machines can be running all at once. * an event loop

I can't think why people don't take opensource seriously. Code this involved requires concise, organised, crystal clear writing. I find the text insulting and stress inducing. It's so vague and sloppy I end up feeling more ignorant after reading it that I did beforehand. You could make a big effort to try and work out what he really means. I wouldn't bother. You can read the rest at http://eekeek.org/poed/poeintro.html as proof I didn't make up this tripe. What would you say if you saw that in IEEE Software?

--some guy

Greetings, some guy. My name is Rocco Caputo. I am POE's creator, primary developer, and with few exceptions sole documenter.

The text you quote and the link you provide are not from POE's documentation. Rather, they are from an early, unpublished draft from a separate project called poed. The particularly silly first paragraph is adapted from something I wrote at http://poe.perl.org/?What_POE_Is . You'll find the original under the heading "Silliness".

Had IEEE Software published it, I would say that they, like you, had not done their homework, and I would question the quality of the publication. Furthermore, if they were to have posted such a scathingly inaccurate review as yours, I would demand a public retraction.

The success of open source projects such as POE and poed rely on the kindness, intellect, imagination and expertise of strangers. Perhaps if you channeled your energies in positive ways, open source projects might one day produce documentation that lives up to your standards. At the very least you should address your legitimate concerns to their authors rather than post poorly researched and unfounded rants on the web.

Thank you for your consideration.

--Rocco Caputo

Meditate about the differences between mall boutiques and garage sales (ignore the fact that garage sales are illegal). Then you may better understand the differences between the POE manuals and, say, the ClearCase manuals. I prefer the POE manuals, personally. But that's only because I hate ClearCase.

By the way, when I was in Nairobi, my expectations for retail outlets first took a dramatic nosedive, especially since many of my relatives' stores weren't, well, to my standards. After acclimating to the realities of Nairobi, I took a walk up the street. Each store was basically the same random assortment of barred and locked randomness, until I found myself doing a double take. I had walked past a Bata boutique, as if it came from inside the Mall of America, except a little bit dustier. Bizarre, bizarre. [pun intended]

The analogy might extend to free software. If you suddenly encountered a professional tech written manual for a piece of free software, your heckles should rise. There ain't no such thing as a free lunch, and with that kind of investment of resources, it's clear somebody wants something from you. For yet another MUD clone, fanboy documentation is what's expected. -- SunirShah

some guy, there is no gatekeeper to the FreeSoftware community, no standards enforcer, Director of Strategy or CEO. Anyone can, and does, slap a (LG|G|M|...)PL on their code and call themselves part of the brotherhood. If you don't like what you find in one area look somewhere else. For me, I find LarryWall entertaining but I'd rather not use his programming languages. Instead I use one of the many extremely well-designed and documented languages like DrScheme or OCaml. You can too. --NoelWelsh

Figure I should comment here since I wrote the above quoted "tripe". I'll keep this short since i'm pretty amused by the whole thing. First off, let me say thati'm actually really flattered at this conversation. I'm very pleased that people are actually reading poed. Regardless of the reactions, I'm glad its making its way into the hands of people. Second, some guy points out that my style of writing hampers the reader's ability to take the documentation seriously. Ironically that's exactly the point. The POE man pages are scattered, dry, and technical. poed's goal is to make the documentation more accessible to newer programmers. One shouldn't have to be a perl god to understand POE. Third, I have a question. some guy, did you happen to read any of the other docs in that set? I'm curious to your reaction to the actual technical documentation as opposed to the lighthearted intro. That's where the real meat of the docs are anyway (well, what there is. poed is still very much alpha). Anyway, thanks all for the good karma from actually reading my stuff and actually thinking about it. This pleases me more than i can say. --Sungo

Hello again. It's now 3 Jul 2009. This page hasn't been updated for almost 5 years (last edit on 14 Aug 2004). In the meantime, POE's documentation has been rewritten from scratch, largely as an effort of a single user (myself) in his spare time (not copious). It's not finished, but you're welcome to review it. The latest release should always be at http://search.cpan.org/perldoc?POE . I look forward to your comments.

By the way, it occurs to me that it's a bit unfair to compare IEEE publications against open source project documentation. The former are professionally edited while the latter are labors of love by amateur writers. If you do find a professional technical editor who wants to work for free, send them my way. Thanks!

--Rocco Caputo

Hi Rocco Caputo,

It's 2011(Yes, I've not read this page again for years.) - and it's the first time I've returned to this page. I'm the guy that used the word "Tripe". I can't remember much of the context. It's possible I may have been arrogant, offensive and not at all considerate of other people when I read about your project. I am not the person I was in 2004 and I'm genuinely sorry. I understand that if people don't have anything constructive to say about open source they should shut up - but if they do, to say thanks for the gift.

-- some guy

Rocco, I'm curious. Even though you found some guy's critique amusing, did it help motivate you to rewrite the documentation? (I am reminded of my father, who used to insert jokes about left-handed screwdrivers into NASA specs).

--CraigPutnam

CategoryDocumentation