Notes from Ruby on Rails Project Night

It’s Back!

Bruce Lee, brandishing "Rails" nunchucksLast Friday marked the return of Ruby on Rails Project Night, a Toronto-based event where developers who worked on Ruby and Rails projects could do in-depth presentations on their current projects or ideas. It was on hiatus for the past couple of months (you can see this entry for the definition of “on hiatus”), but thanks to the efforts of Corina Newby, who helped put together the event at its old venue, it’s back, and judging from the attendance, it was missed. Thanks, Corina, for all your work!

James Robertson

The first speaker was also the special guest (and the reason the event was held on a Friday, as opposed to the typical Monday or Tuesday): James Robertson, whom you may know from his blog Smalltalk Tidbits, Industry Rants. He was on a “Canadian tour”, during which he was talking about the Smalltalk-based web app framework Seaside as well as Webvelocity, which puts the Smalltalk development experience within the browser.

Here’s the abstract for his presentation (from this entry from Corina’s blog):

WebVelocity is a new Smalltalk Development Environment that is oriented around Seaside for Web Development and Glorp for Object/Relatonal Mapping. Come and see how WebVelocity re-targets the Smalltalk development experience into the Web Browser and simplifies the challenge of learning a new environment for newcomers. We’ll even build an entire application using Active Record and Scaffolding during the presentation, with minimal programming. If you’re a fan of Ruby on Rails, you need to come out and see this presentation!

Here are my notes from his presentation:

- Seaside is open source, but Smalltalk ain't
- Seaside is maintained in Squeak, which you could call "the open source Smalltalk"
- Ruby on Rails is opinionated
- "Seaside is also opinated; it just has different opinions"
- When building Seaside, Avi Bryant asked "What if I took all the assumptions about web apps...
  and ignored them?"
- Some of what I show you is what happens when you blow those assumptions

- The canonical Seaside example -- the number increment/decrement button
  (now we know where that disastrous DemoCamp Seaside presentation came from!)
- Seaside uses continuations to remember state
- They enable "proper" support for the backbutton
- Session state info is keyed via a cryptographically secure key in the URL
- With Rails, you're dealing with two different worlds: templates and code
- Seaside is just one world: You don't write any HTML at all, you write all Smalltalk
- It's all in one place
- Support for debugger -- you can debug web apps as if they were desktop apps, with breakpoints and resumes
- In Seaside, the "html" argument is a "brush" that knows how to "paint" HTML
- You can debug in the middle of a page hit
- In beta: Seaside totally within the browser
- Editing code within a webpage, including tooltips and color hinting
- Every time a method is entered and it is syntactically correct, it is auto-saved -- no need to manual save!
- [Shows a Smalltalk debugger with an Ajax front end]
- "In some ways, it's even more productive than the real Smalltalk environment is"
- [Smalltalk console within the browser]
- [Auto-indenting within the browser]
- [Auto-generates a scaffolding-like page]
- The "call" method lets you write web app code very much like writing GUI stuff

Paul Doerwald

The second speaker was Paul Doerwald, who changed his topic from the more Ruby/Rails-specific “insights gained from working with ActiveRecord validation” to a more general (but still interesting) topic: Agile Documentation. He figured that it might be a better fit with James’ presentation, and it was — it was also quite interesting.

Here’s the abstract for his presentation:

“Programmers generally hate writing documentation. That’s because most documentation is kept separate from the code and becomes hard to keep up-to-date. Besides violating the DRY principle… it can lead to misleading documentation, which is generally worse than none at all.” [Subramaniam/Hunt ’06]. Why do developers hate writing documentation, and why do stakeholders and managers keep requiring it? Is there agile documentation beyond inline API documentation (JavaDoc, RDoc, etc.) and comments in the code? What parts of a project deserve separate-from-code documentation? How do we identify them, capture them, and keep them relevant?

Tonight’s Toronto Ruby on Rails Project Night presentation discusses the problem of documentation, explores some key aspects to consider when writing effective documentation, and dreams of a future of testable, executable documentation, where non-code knowledge could be integrated into your code.“

And here are my notes from his talk:

- My original presentation was going to be about insights gained from ActiveRecord validation
- But I've decided to change it -- it's now on Agile Documentation
- It's my M.Sc. Thesis!
- "You'll find this talk a bit heavy on problem and not so heavy on solution"
- Think of this as an introduction -- I want to frame things and ask:
  what is Agile Documentation?

- By "documentation", I mean by the kind that's by programmers for programmers
- It's not a particularly sexy area
- Frameworks are sexy:
    - Rails is sexy
    - Django is sexy
    - CakePHP is sexy...(for PHP)
- Languages are sexy
    - Ruby is sexy
    - Objective-C is..."strangely alluring"
- Even databases are sexy! Consider CouchDB and AWS
- What's not sexy?
    - Documentation
    - Backup -- at least not until Apple's Time Machine
    - Both are viewed as a waste of time
- We're developers. We may grudgingly accept the presence of non-developer things,
  but we don't want to do them
- Documentation is hard to write
- It seems so much easier to program rather than write
- Writing -- the non code-type -- is not our core competency
- We say "Our code is the authoritative documentation!"
- Consider what DHH said in a "Signal vs. Noise" blog entry in February 2006
    - When asked "How do you document your projects?", he replied "We don't."
    - He also said:
        - "Never worked consistently or successfully"
        - "Not necessary for our work"
        - "Most Rails developers can walk in and find out"
        - "We use Ruby"
        - "Method docs only for non-obvious behaviour"
        - "Docs mean BDUF"
        - "Appropriate only for onerous enviroments with complex policies"
        - "Focus on code quality instead"
- Like backups, docs are important
- We're not the only people who'll be working on a project, especially if it's a success
- We don't want to feel like we're wasting time when we're working
- Running a documentation tool and taking its output and pasting it into a Word doc is not DRY
- Why are we writing highly-coupled docs?
- Is there such a thing as agile documentation? I'm going to say yes
- Look at the Agile Manifesto
    - "We value working software over comprehensive documentation"
    - But it doesn't say that comprehensive documentation isn't valued!
- What's the state of the Art
    - For API Documentation, it's JavaDoc
    - In Rails, the outer classes are well documented, but not the inner ones
    - The JDK is extremely well-documented
    - You could say that RSpec is a form of agile documentation
    - It's a stretch, but Domain-Specific Languages could also be agile documentation
    - After all these, I can only think of process
    - When do we do docs? At the beginning of the process? At the end?
- What could agile documentation look like? What does it feel like?
- I borrowed principle from Alastair Cockburn's "Agile Software Development:
  The Cooperative Game, 2nd ed."
- The goals set out in the book:
    - Finish the game (i.e. finish development and launch the product)
    - Set up the game for the next team
    - Think of pool: maybe you take the hard shot first to set yourself up later for the easy shot
    - Coburn calls this "residue": the stuff that one team leaves behind for the next team
    - Residue includes:
        - Code
        - Process in place
        - Documentation

- I would argue that DHH/37signals has an oral form of documentation
- It works if the company doesn't grow too quickly
- What are we really asking for when we ask for the documentation: Tacit Knowledge
    - "That which is seen but not noticed"
    - It is information that is understood and implied but not stated
    - If you've ever brought someone else onto a team, you spend a lot of time
      explaining things that are obvious to you
    - You might not explain that stuff if you're doing it on paper
    - You don't want to end up in a situtation where there's too much documentation
- What can we borrow from software engineering principles?
    - Orthogonality
        - A good thing in software development
        - Intersect at a clear and obvious point and do not influence each other at any other point
    - Cohesion
        - All attributes and methods are related to the essence of the class
        - Don't have people look in 5 different places to get the answer to a single question
    - Coupling
        - The extent to which one thing is dependent on each other
- To the future
    - 5 years ago, unit testing was unheard of in the web development world
    - Rails and similar projects have helped popularize unit testing
    - We've moved from the point to where we say "testing is awesome"
    - Testing is now a core value
    - Can we make documentation a core value?
- Agile documentation processes
    - Large companies are good at this; open source people not so good
    - Looking to Rails:
        - Documentaton conventions?
        - What if we had 5 steps for writing documentation that did 70% of the work?        
    - Can we integrate documentation with code?
        - In many cases, the docs exist as a Word document
        - A step up is to use a Wiki -- support for multiple authors, versioning, linking
        - Can we put docs right in the codebase?
        - Every Rails app has a doc directory -- can we use that?
        - We test code -- is there a way to make testable documentation?
        - What if we could tag a method and class with a keyword and make that keyword appear in the docs?
          -- We could generate an alert when changes happen

Checking Out the Rich Media Institute

After the presentation, which was held in the Rich Media Institute’s basement-level lecture room, a number of us headed upstairs to check out its main floor. If you’re a techie with a creative bent, this place is like a candy store. The front part is a store full of books, t-shirts, music and other goodies that new media creators and aficionados would love, while the back is a gallery for local interactive artists’ works.

I took some photos of the place and posted them in the gallery below. Click on any of the thumbnails to see a larger version of the picture:


Creative Labs: Where No Good Deed Goes Unpunished

Creative Sound Blaster Audigy/Vista Incompatibilities

A “Screw U” patch with the Creative Labs logo overlay.

The Audigy series of Creative Labs’ Sound Blasters lost some functionality with the release of Windows Vista:

  • EAX: “Environmental Audio Extensions”, a set of digital signal processing presets that are meant to make sound in games seem more realistic.
  • 3D Audio
  • Sampling rate conversion
  • Audio mixing

Creative’s story is that Microsoft removed “the ‘Vendor Extension mechanism from Vista’s DirectSound implementation,’ which is what Sound Blaster Audigy relied on to generate EAX effects and other audio processing.” Without this bit of code, Sound Blaster Audigy cards produce regular 2-channel stereo sound and not the supposedly more realistic-sounding, spatially-localized sounds for which people bought Audigy cards in the first place.

If this development wasn’t enough to upset Audigy owners, Creative stirred the pot last July by charging $10 for software called Creative ALchemy (that’s not a typo — the first two letters in “ALchemy”, when referring to the software, are supposed to be capitalized). Here’s the description from its page on Creative’s site:

Creative ALchemy (Audigy Edition) restores your Sound Blaster Audigy’s ability to process EAX effects, 3D audio, sampling rate conversion and audio mixing for certain DirectSound3D games in Windows Vista.

Quite predictably, some users were quite annoyed at being asked to pay for this software. In the words of this Gizmodo article, Creative was effectively “charging 10 bucks to fix something that should work in the first place.” A commenter in this CrunchGear article on the issue made a point that the charge could reflect the extra development effort required in making Audigy cards work under Vista, but also suggested that Creative could’ve eaten that cost “for PR purposes”.

For more commentary on Creative Labs’ charging $10 for what some saw as functionality that they had already paid for, see this ZDNet article titled Creative charging $9.99 for Vista EAX update?.

The Good Deed and the Punishment

In the comments for the Gizmodo article I cited earlier, there’s a reference to a free software workaround that enabled the features lost with a Vista upgrade. The workaround was posted to Creative’s forums and the commenter felt it necessary to note that the post “surprisingly, hasn’t been removed yet”.

It’s quite likely that the workaround in question was a solution posted by one “Daniel_K”. Here’s what a Gizmodo article posted yesterday has to say about it:

Developer, good-guy and all around hero, Daniel_K stepped up to the challenge, putting together his own drivers and asking for non-obligatory donations in recognition of his effort. Daniel_K’s drivers restored functionality, and added some extra features to boot.

You might think that Creative would be pleased: here’s a user with the will and the skill to develop a software fix that restores functionality to their hardware under Vista — essentially crowdsourcing at its best.

However, they were not pleased. Here’s a message posted to their forums by Creative’s VP Corporate Communication, Phil O’Shaughnessy. I’ve emphasized the part of the message that really grind my gears:


We are aware that you have been assisting owners of our Creative sound cards for some time now, by providing unofficial driver packages for Vista that deliver more of the original functionality that was found in the equivalent XP packages for those sound cards. In principle we don’t have a problem with you helping users in this way, so long as they understand that any driver packages you supply are not supported by Creative. Where we do have a problem is when technology and IP owned by Creative or other companies that Creative has licensed from, are made to run on other products for which they are not intended. We took action to remove your thread because, like you, Creative and its technology partners think it is only fair to be compensated for goods and services. The difference in this case is that we own the rights to the materials that you are distributing. By enabling our technology and IP to run on sound cards for which it was not originally offered or intended, you are in effect, stealing our goods. When you solicit donations for providing packages like this, you are profiting from something that you do not own. If we choose to develop and provide host-based processing features with certain sound cards and not others, that is a business decision that only we have the right to make.

Although you say you have discontinued your practice of distributing unauthorized software packages for Creative sound cards we have seen evidence of them elsewhere along with donation requests from you. We also note in a recent post of yours on these forums, that you appear to be contemplating the release of further packages. To be clear, we are asking you to respect our legal rights in this matter and cease all further unauthorized distribution of our technology and IP. In addition we request that you observe our forum rules and respect our right to enforce those rules. If you are in any doubt as to what we would consider unacceptable then please request clarification through one of our forum moderators before posting.

Phil O’Shaughnessy
VP Corporate Communications
Creative Labs Inc.

Simply put, Creative is saying that by fixing stuff that they’ve broken on purpose in order to gouge more money out of their customers, you’re stealing from them. It’s just another case of a vendor seeing its customers as “batteries for their Matrix”, or a Jay Michalski puts it, gullets that live under the end of the distribution system’s conveyor belt, where they gulp down products and crap out cash.

Oddly enough, there are a couple of commenters to the Gizmodo articles who come to Creative’s defense, one of whom brings up the fact that if Daniel_K did any reverse engineering of Creative’s drivers for Audigy cards, he broke the EULA. These people are the sort that Dante was thinking of when he wrote about that part of the 8th Circle of Hell reserved for evil counselors.

Pig labelled “Creative Labs” gorging on food in a bucket.