Forum OpenACS Q&A: Greenpeace: Pay up!

Collapse
Posted by Tom Jackson on

Why should I keep complaining about ad_form? Because it has no documentation. I'm no longer going to waste my time arguing with a few know-it-alls about how easy it is to use. I'll just stick to a simple argument. Greenpeace paid for software development that they are benefiting handsomely from. They have paid a gatekeeper to include this software in our toolkit, but they failed to pay for documentation. Greenpeace is polluting out toolkit with undocumented and hard to understand code. Clean up your mess! ... Please.

I urge other developers to boycott ad_form until Greenpeace cleans up their mess and promises to pay for any code and documentation changes resulting for future incompatible alterations of ad_form, or bug fixes required.

If they fail to clean up their mess, I think we should vote to remove ad_form from the core of OACS, and ban the use of ad_form in core packages.

Arguing that ad_form is just a 'wrapper' for the form builder is like arguing that OACS is just a 'wrapper' around AOLserver. Gimme a break. Document your API and include:

  • All possible switches, including the order in which they must appear.
  • All magic words.
  • Problems of evaluating code at the level of the template.
  • Problems of subst'ing code at the level of the caller
  • How to use every widget, including methods of selecting data from a database to fill in API parameters.
  • Complete examples of using non-default behavior.
  • Useable comments in the source code.
  • How to debug a stateful page when things screw up for the user.
  • How to debug during form development.
Collapse
2: Re: Greenpeace: Pay up! (response to 1)
Posted by Peter Marklund on
Tom,
I don't myself know much about either the form builder, and I've only used ad_form once. My experience with ad_form was positive and I found the resulting code was quite concise and readable.

As far as documentation goes it seems to me the proc is already far above OpenACS average. I would like to have some guidelines though about when to use ad_form versus the form builder directly.

I am curious to know what you have been trying to do with ad_form and how that failed.

When I find a proc that is missing documentation or has incorrect documentation I try to amend that. I encourage others to do the same.

Collapse
3: Re: Greenpeace: Pay up! (response to 1)
Posted by Don Baccus on
I just checked your cronjob package and see no documentation whatsoever.

I tell you what, Tom ... when you reach the level of documentation for your contributions to the toolkit to that you demand of others, I'll listen to you.

Having said this ... it *is* mostly just a wrapper around the form builder, and documentation on widgets, datatypes (like the "date" datatype that give folks fits) should be written for the form builder in general, not ad_form.

Because not everyone will use ad_form, some will use the form builder directly.  So widget docs etc really belong there.  I do plan to write documentation once things calm down a bit.  Currently I'm quite busy pushing 4.6.2 and dotLRN 1.0 out the door.

As far as blaming Greenpeace goes ... posts like this will just encourage clients to refuse to GPL their code.  They've found the documentation reasonable for their needs, and that's really all they should be asked to pay for.  Make unreasonable demands of paying clients and they'll just stop giving code back to the project.

No one is forcing you to use ad_form.  If you don't like it, don't use it.  Other people are using it because they find it a lot easier to use than the form builder natively.

One result of this is that new features have been added by others that haven't necessarily been documented. Surely you can't blame Greenpeace for the actions of others.

If you insist that ad_form not be used in core packages, will you pay me for the extra time it takes to write form-handling pages using the form builder natively?  I find it takes me about 1/2 as long to create such pages using ad_form and that they typically work the first time.  I'm sure as hell not going to eat that time for free just because you don't like the code.

Collapse
4: Re: Greenpeace: Pay up! (response to 1)
Posted by Don Baccus on
To set the record straight ...

Greenpeace did not pay me to include ad_form in the toolkit.  I developed as part of my work on their project, and everything done for that project is GPL'd.

So it is proper to say they made this and other code *available* to the project.  You make it sound as though they paid me to put it in the toolkit so they'd profit from the misery of others - well, you anyway, other people mostly like it - and that's far from the truth.

I showed it to others, people liked it, ummm ... and actually told me they thought the inline documentation was pretty decent, to make another point of fact ... and with this favorable reaction it landed in the toolkit.

Lastly ... why all the anger?  It's just a friggin' piece of code.  It's documented at about the same level as the in-line documentation of ad_page_contract - should we remove that, too, until it meets your high standards?

Collapse
6: Re: Greenpeace: Pay up! (response to 1)
Posted by Talli Somekh on
I spoke with Tom at the Seattle social, so I understand his frustration.

But I have to agree with Don that it's not fair to call them out as I can strongly attest to GP's massive contribution and even stronger commitment to the OpenACS community. There are a  few large institutions who have begun to participate and then pulled out when they thought they could do better than being a part of a group, and GP for sure isn't one.

The issue of better documentation is important, but we don't want to piss anyone off before they contribute. Open Source is voluntary, of course, and taking off when not being appreciated is an all too familiar response.

talli

Collapse
5: Re: Greenpeace: Pay up! (response to 1)
Posted by Randy Ferrer on
"I urge other developers to boycott ad_form until Greenpeace cleans up their mess and promises to pay for any code and documentation changes resulting for future incompatible alterations of ad_form, or bug fixes required."
No way and here's why...

I'm new to developing in the oacs environment and if I were to take this attitude, I would be in for some serious disappointment working with the toolkit. Since ad_form is the piece of code in question let me address that. I've been using it and enjoy working with it. It was a bit of a puzzle at first. I looked at Jon Griffin's docs, went through the code and have gone through much of the forum. It took a bit of effort, but I feel the benefits are well worth the results. Do I have more questions - sure. Are Greenpeace and/or Don responsible for this? Of course not. At the end of the day, I chose to use the code - after all, there are other avenues open to accomplish what I intend. I also chose to use OACS as a development platform for some of my projects - 'nough said.

Much the same case can be made for many parts of the toolkit and sometimes it is very frustrating, but having said that, let me point out that if there is a continous theme that runs throughout this community is that of better documentation. Continous efforts are being made to improve and extend the docs by Joel and many others and this comment seems to imply that is not the case. This is not a very positive thing... Greenpeace is not to blame, gatekeepers are not to blame. I hope that as a community we can do better than misdirected anger and calls for boycotts and such. Does anyone seriously think that any good will come from calling Greenpeace and others out in this manner?? Look, we all need assistance at some point and the more experienced amongst us sometimes have time to help and sometimes don't but in the end we are responsible for the choices we make in developing software - no one else. It is also our responsibility to help the community move forward in whatever way we can. Greenpeace has made contributions already by paying for and releasing software under the GPL. They certainly where not obliged to do that so is it fair to blame them for not reaching a "higher" standard of documentation on this piece of code? Again - no.

I think the suggestions made by Tom are really good and would certainly go a long way towards making the toolkit a lot friendlier. So, I think there is a lot of good, common ground here if we focus on doing what's really important - making the toolkit the very best it can be and not on trying to place blame. Again I know how frustrating it can be sometimes to work through some parts of OACS - but I don't believe a boycott of anything is the answer. If anything, it can have very negative repercusions for the community as a whole - is this really what is desired??

Collapse
8: Re: Greenpeace: Pay up! (response to 1)
Posted by Don Baccus on
I also have to wonder why Tom's claiming that NO documentation exists, when clearly some does.

Tom, I encourage you to read that and to make specific critiques as to which parts are unclear and which parts are confusing to you. That would be far more productive than making the false statement that "it has no documentation".

Sadly it's not been kept entirely up to date and revisiting this is something I'd like to do ... and perhaps if I were to insist that folks who add extensions to my previously pristine code (yeah, right) not do so unless they change the documentation, too, we'd see fewer extensions! Hmmm....

Anyway, yes, this is a basic explanation of the proc but it was 100% accurate when I lifted it from Greenpeace and put it in the toolkit (again, after discussing whether or not folks wanted it in the toolkit.)

And Jon Griffin has written additional documentation. I answered questions, and Jon wrote. I liked that approach because people who write code are often blind to which bits will appear confusing to others. Jon was sufficiently confused that he asked good questions that wouldn't've occured to me, as author of the code. If you feel Jon's document's not helpful, insufficiently clear, etc I'm sure Jon will welcome specific suggestions for improvements.

So far what's clear to me is most folks are thoroughly confused by the form builder's date type and I have to admit that I am, too. When we inherited ACS 4.2, the date type wasn't working and wasn't fully implemented. I finished it up to a minimum level and left it. It needs a lot of work, and needs documentation.

But ... the problems folks run into with the date datatype are there to confuse you if you use it when calling the form builder directly. It's truly a form builder issue.

Now ... if ad_form grows to the point where direct use of the form builder is never needed, and if we convert all packages to use it ... then I'd agree that all widget documentation etc should be gift-wrapped in a general document about ad_form, and that form builder documentation (at least the generation side, not the template tag side) be thrown out.

But currently ad_form still doesn't handle every possible case. It's not clear it ever will. Until or if it does, things like widget documentation needs to live in the form builder docs. So far no one's stepped up to the plate to document the existing form builder properly. It was poorly documented before I wrote ad_form. It's poorly documented now. Feel free to volunteer to grok the form builder widgets and to document them. Don't throw stones at me or Greenpeace over this, though, because I DIDN'T WRITE THE FORM BUILDER!!!!!

Collapse
7: Re: Greenpeace: Pay up! (response to 1)
Posted by Tom Jackson on

I didn't know my cronjob package was a core package, but even so, I agree that it could use some documentation. If anyone has been confused by it, I haven't heard from them.

I'm sorry about the reference to GreenPeace. They are mentioned several times in the body of ad_form and in the documentation. I assumed it was their baby. The fact that Don contributed his time to develop this makes the level of documentation much more understandable. I guess the task of documentation falls on all of us, including me.

If Greenpeace is reading: I fully appreciate the financial, technical and moral support they have brought to the OpenACS community.

As I asked a week or so ago in another thread, if anyone has nonstandard examples, or even standard ones, please email them to me.

Don, I'm not angry, I'm concerned. I'm concerned, not about development time, but maintainance, upgrade and support time. Documentation would really help, it may even help figure out when direct use of the form builder would work better.

Collapse
9: Re: Greenpeace: Pay up! (response to 1)
Posted by Don Baccus on
Well, improving documentation of this, for the form builder, and for relational segments are on my personal want-to-find-time-to-do list.

But picking on ad_form itself is awfully unfair given that the hardest parts to understand are directly attributable to the form builder which we inherited from aD in largely undocumented and, indeed, incomplete form.  I'd love to see all the form builder widgets documented.

For instance if the date "get_property" and "acquire" functions were fully documented, then my comment in the ad_form API header that "to_sql() calls the datatype's get_property proc" would be a useful hint to read that documentation.  Unfortunately no data type documents its "get_property" proc so my hint leads to a blank page.

But it ain't *my* fault as the author of ad_form that datatype documentation doesn't exist for the form builder ...

Go pick on Karl Goldstein over this and leave me out of it!

Though my gut tells me that I'll probably end up writing the documentation in my copious spare time, because I understand it better than anyone else in the OpenACS project at this point.

Collapse
10: Re: Greenpeace: Pay up! (response to 1)
Posted by Bruno Mattarollo on

Hello Tom,

I find these comments very sad for a few reasons.

  • they are not based on reality
  • your comments would imply that if we pay a gatekeeper we could get any shit code into the core

First of all, the comments from Don portrait quite well what is the reality and I can also tell you that Greenpeace is not interested in making OpenACS a Greenpeace-specific framework, on the contrary! We are firm believers in the value of open source and I think that we have shown it so far, if not look as well at the co-funding of Worflow with MIT and Heilderberg and other projects in which we are involved.

If your comments were true then we would have added all the custom made code that we have added to the request processor just to suit our needs.

On a personal note, I have used ad_form without the need to have more documentation than the source code. Don't get me wrong, I am not saying with this that it's the best documentation ever made available to mankind, but I am saying that the comments are usable and with that you can make use of ad_form.

Having said all that, I do believe in documenting code and I agree that we have to do our best to have high quality docs with the toolkit but this type of rant is not good for the community.

This is my personal opinion and doesn't reflect necessarily an organizational position.

Collapse
11: Re: Greenpeace: Pay up! (response to 1)
Posted by Tom Jackson on

Bruno, I already said I'm sorry for bring Greenpeace into it. That was a mistake based on the fact that the documentation and source code for ad_form both mention Greenpeace. Also, it is no secret that Don developed it while working with Greenpeace specifically for his work on the Greenpeace sites.

The fact that ad_form can be understood by reading the source code is irrelevent to my argument. You represent a relatively large organization that can afford the best available developers, and you do afford them. Your orgainization has brought quite a lot to OpenACS, to the toolkit and the community. Thanks for that.

The problem I am having with ad_form is a result of it's uselfulness. People are using it. ad_form is enabling the use of the underlying form builder. It didn't matter that the form builder was underdocumented, it was really too hard for most developers to use. ad_form has enabled the use of this underdocumented part of the toolkit, which in the end really requires that you understand the form builder.

Now being a large organization with sufficient funding to maintain your web applications doesn't give you the same perspective as a small organization would have. If you need to debug a single page, or extend the toolkit in a simple way where ad_form has been used, now the problem starts. Instead of simple job of understanding the traditional tcl/adp page series, you have to figure out stateful pages that go through several underdocumented layers of api code.

I have yet to run into this issue, I admit. But I see more and more use of ad_form, some in core applications, because it speeds up development, or so it seems.

Next, I guess it a difference in development styles. ad_form uses widgets to generate html code. All the examples I have seen just have the formwidget tag on the adp template page. When I write adp pages for a tcl file, I like to "document" what varibles are being used, by using them. Then the next time I visit that page to fix some problem, I know what I need to do. When I read an ad_form page, and the adp template, I have very little idea what variables are available to use. In order to make a change, I need to understand ad_form and the form builder.

The ad_form code is understandable, but it isn't the kind of code that should be generally read by developers, unless they find ad_form doesn't do what they need and they want to extend it.

So, again, my concern is that ad_form is being used more and more, in some cases in the core of the toolkit. These changes are being made by folks who understand ad_form. But now everyone who uses these packages really needs to understand it, and form builder, as well. The traditional approach of setting up data sources in the tcl page and then providing markup on the adp pages is mixed up with form builder and thus ad_form. The inevitable result is that changes which could have been done by graphic artists, and html editors, now requires the work of the tcl programmer. This means that the toolkit will be harder to adopt by newbies and more expensive to maintain.

Collapse
12: Re: Greenpeace: Pay up! (response to 1)
Posted by Dave Bauer on
Tom, ad_form, or form builder, you can still use a site-wide formtemplate. So instead of making up each form individually, you can include the form template using a <formtemplate> adp tag. So all the adp markup that renders the forms is in one place. This makes it easier to maintain.

I have used the form builder, and ad_form to build real applications. I found ad_form made it faster to implement. Whenever I have run into a limitation, I have had to check through the source of the acs-templating package to figure out what exactly is going on.

You have referred to graphic designers making changes.Using a site-wide formtemplate, they can edit the master form template to change the look of the forms.

I really think the problems come from the incomplete form builder documentation. I have had to learn almost every part of the toolkit by reading the source code, so I know that the documentation is lacking. I think there is a definite effort to impove the documentation of the entire toolkit. Just remember this will take time.

Collapse
13: Re: Greenpeace: Pay up! (response to 1)
Posted by Kjell Wooding on
Good lord. We're talking about an open source project here. Hundreds of people have worked on the project and donated the code. If you find something is deficient, (and that includes documentation) FIX IT. Submit diffs. That's how open source works.

If you want to demand someone do work that you're not willing to do yourself, pay for your software. The open source world is not for you.

Collapse
14: Re: Greenpeace: Pay up! (response to 1)
Posted by Tom Jackson on

Kjell,

Thanks for your lesson on how open source works!

I guess I should just go home and fix my own contributions to the toolkit.