Notes from Ruby on Rails Project Night

It’s Back!

Last 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: