Post Spec - my talk at BarCamp Toronto
Posted on:
2006-05-14
I was at BarCamp Toronto (BarCampTDot) yesterday and had no idea what to expect. The notes said that everyone had to take part, so just in case I put together a short presentation on some agile-style practices that I've found useful lately. After attending a few sessions, I figured what the heck and put my name in for the 7:30 - 9pm slot. I also brought along a bottle of Highland Park 12 Year Old Scotch Whisky as a small bribe. A fair number of people showed up and, although it was really loud in the space and I'm not sure if I could be heard very well, I think things were well received and we had a good (if lubricated) discussion afterwards.
I spoke from notes I put together in OmniOutliner. They're not exactly what I said, but they're pretty close. This is an 'export-to-HTML' with some formatting tweaks.
Introduction
This talk is called POST-SPEC. It's some of my ideas on application development.
- What does Spec stand for - really - Specification? or Speculation?
- Post-Spec means 'after the spec' - moving beyond the 'architectural' idea of the blueprint-specification.
- Post-Spec also means 'spec at the end', which is a practice that I've started using with pretty good results.
Who I am and where I'm coming from.
- Freelance work for 10 years - 2 years at a consulting firm in the US.
- Lotus Notes/Domino back when it was doing cool and interesting things.
- Then Java/JSP and PHP and now Ruby on Rails.
- Small business applications
Thoughts on Specs
Why specs?
- Software used to be DIFFICULT and EXPENSIVE. Processing power was expensive and rare.
- Software projects required lots of planning and resources. Dozens or hundreds of programmers.
- Specs were required to keep these massively expensive projects on track and to marshall the hundreds of people who may be involved at any one time.
The new world of fast and agile development
- Now languages and processors have improved so that development is fast and responsive.
- Java was pretty good - and then lost its way in the Swamps of J2EE - it needed 'Enterprise' and boy did it get some - then Perl, PHP, Ruby started making an impact.
- What used to take a division then a large team can now be done with a small group or even an individual.
- The need for coordination and overarching planning isn't there anymore.
In fact, now that things are nimble, the failings of having a big up-front spec are more apparent.
- The standard spec is written by an 'architect' - someone who doesn't program or work in the business context - but someone who just writes specs. I could rant about architects, but I'll leave that for another time.
- You don't really know what's going to happen until you're doing it. Wicked problems - Tacoma Narrows Bridge.
- Many people describe a spec as a map - but what use is a map of a place that the cartographer never been? Ever seen those old maps of the world, with Atlantis and lots of 'Here Be Dragons'?
- Specs written before programming are obsolete as soon as real code gets written. In fact they're worse than wrong - they're dangerous - since their impression of authority can lead to people trusting them when they're wrong.
A Post-Spec Methodology
Planning
- Use your favorite method for getting an idea of what needs to be done.
-"Stories" on file cards, diagrams, Napkin-driven development.
- Not mock-ups, necessarily - see below.
Get it out there as fast as possible
- Instead of mock-ups, build a simple version of the real system. This is feasable now.
- Have the ideas collide with the real world as soon and as quickly as possible
- Get people to use your application for their actual work
- Make sure there's a flexible back-end for jimmying things that don't work correctly.
- Put in lots of extra 'notes' boxes, so people have somewhere to put data that doesn't fit otherwise
- In my experience, no matter how careful and meticulous you are - no matter how much you plan ahead, the first hands-on session with a user is going to blow your mind.
- Nothing can find the leaky parts of an application quicker than a half dozen untrained users. They'll cause errors and data corruption you never would have imagined.
- USE MURPHY'S LAW TO YOUR ADVANTAGE.
- Also, if they don't understand it, you may need to clean things up.
Iterate - this is where the screaming happens
- Get things out there quickly. Get them to break really early.
- Set up error notification through email if possible, or at least somewhere in the system - with a session dump and a stack trace - so you can find out about errors as soon as they happen.
- Set up some kind of mechanism for people to provide feedback - you're a developer, build one! It ought to be really simple.
- Two kinds of issues: Errors and Requirements Changes
- Fix things that blow up as quickly as possible.
- For requirements changes, get a regular schedule for review meetings about the requirements - include a programmer (you?), a person who actually uses the system, and the person in charge of the business process - getting these three people in one meeting can be diffficult, but it can save WEEKS of dead end development. It's amazing how a bit of an adjustment from one of the three can make things much easier for the other two.
- Don't aim for perfection - aim for results
- THIS ISN'T BAROQUE COUNTERPOINT - THIS IS PUNK ROCK. IS IT CLOSE ENOUGH FOR ROCK?
After things slow down - THEN you write your spec.
- Specs are like maps. They describe the territory. What are maps used for in the real world? Exploration? Not really - since if there's already a map of the area, why explore? Maps are drawn BY the explorers for other people to use afterwards. Specs should be the same. They help future developers or maintainers - and all of the other stakeholders - to understand the territory.
- Wordsworth describes poetry as 'emotions recollected in tranquility'. Your spec should be like that. Coding is intense and tumultuous - documentation should be a time for review and reflection.
- Go through the code class by class and method by method and write things up in plain English. This isn't JavaDoc - it's something that anyone should be able to read if they really wanted to. It describes what the system does.
- As you go through, you'll start to notice stuff - 'wow, that was stupid'. 'That's an awkward way to do things'. 'This should really move to this status instead'.
- Fixing these is easy, since you've already got a compelete set of unit and functional and integration tests - don't you?
- You can run them while you floss your teeth and pay off your credit card and eat a balanced meal with lots of fresh vegetables and fiber.
- If you don't have tests, here's your chance to tie things together - the changes have slowed down enough for you to actually build tests without having to redo them every time the logic changes.
- Likewise, you've also commented everything - haven't you?
Then finish your user documentation and refactoring.
- 37Signals note that it's better to use developer resources to do more code than to write things up. This is true, but after things slow down, writing things up is development. It's refactoring. It's streamlining. It's understanding the system thoroughly. It's helping users and future developers figure things out.
