One of the core technologies used in many web sites is some kind of form handling. It’s one of the the basic ways users interact with the site. My travails so far have led me to bump into no less than four packages for Catalyst.
Those would be:
The thought just crossed my mind to check the Catalyst Wiki and (lo! and behold!) there’s a page with pretty much the same list. There was also something about Rose::HTML::Objects, but I’ve not looked at that yet and can’t comment.
Reaction seemed like a bit of overkill for my current project, and the documentation was *ahem* a little sparse, so that left me to choose from the first three listed.
I have been reliably informed that FormBuilder is officially passé and no one in their right mind would even consider using it. My counter-argument that the samples and tutorials were all using FormBuilder now seems to be moot as someone has changed the tutorial to use FormFu. I see the name Kennedy Clark on that page, so doubleplusgood there, sir. 🙂
I moved on to FormFu and was told I shouldn’t bother because it was in the process of being superseded by FormHandler. I’m always wary of being on the bleeding edge, especially with OpenSource projects. The FormFu docs made my head hurt marginally less, so I’m moving ahead with FormFu.
The FormFu reference documentation seems to cover the bases (which isn’t always true in open source projects), but there seem to be a number of serious gaps. For example, all the samples are in YAML, so if you don’t grok YAML–well, no samples for you… This happens a lot in open source projects where the samples, examples, etc. are all written by a small group with a shared mind-set. So far it’s only slowed forward progress, but it’s still sub-optimal.
Another example–and this is endemic to open source projects–is a lack of practical, “how do I do the obvious” type of documentation. Yeah, I know… it’s obvious so why does it need to be documented?
First, any two people making a list of things that are “obvious” and things that need further explanation will frequently create very different lists. Second, making the list itself requires serious introspection. It is easy to miss things that are completely invisible either to outsiders with limited knowledge or to insiders with “too much” knowledge.
This brings me to my current conundrum. I’m at a unique moment here–I don’t know too much, so a lot of what’s missing in the documentation is still fresh or soon-to-be-discovered. I’m making notes about the problems I’m encountering, where things are hidden, and making cheat-sheets about what the other folks I’m working with will need to know so they can come up to speed. That’s exactly the kind of thing that should go in the documentation, right? So…
- Is FormFu on the cusp of being superseded? Would it be a waste of time to try to contribute to the documentation of a project about to become passé, like FormBuilder before it?
- Are the FormFu folks receptive to documentation contributions? That would include answering questions and actually including new or updated docs.
(Hey! Look! A Poll over there in the sidebar!)
My limited dealings with the open source “community” hasn’t completely crushed my belief there must be reasonable, adult, professionals out there but the use of “source is available” or “RTFM” as some sort of be all, end all of knowledge transfer leaves me cold, both as a coder and as a writer.
Hm. It’s late and I feel a rant coming on so I’ll stop here.
More as it happens.