(This is a snapshot of my old weblog. New posts and selected republished essays can be found at raganwald.com.)

Tuesday, October 11, 2005
  Fully Engaged by Example

First, a personal note. I'm feeling fully engaged. You know that feeling, when it seems like what you're working on occupies 100% of your attention, when you have to fight to think about anything else.

This weekend I went climbing in Kentucky. On Saturday night I was at a rocking party with some of my most attractive friends dancing up a storm. I was in a corner, writing down thoughts about how my project would help people communicate about software functionality using examples. And I love to dance!

Sometimes a dance is just a dance, but an idea is a dream coming to life. I didn't want to miss the moment. Do you ever feel like the entire Universe is conspiring to move you forward? It isn't really, but it feels that way because you're so positively attuned to your idea that you can find help from even random outside events.

And after a weekend working on examples, what do you suppose I spied on a church billboard driving home?

Okay, now about examples. Here's the pain point in development. How do we communicate about what we're going to build and why over the life of a project, not just in version 1.0?

Jonathan Edwards does a terrific job of explaining the problem:

Programmers in the real world will tell you that specs aren’t worth the paper they are written on. They are half-baked informal descriptions that are too abstract to be understood by the users, and too imprecise to be useful to the programmers. They are full of internal inconsistencies and factual errors, because there is no way to test them. They are obsolete the day they are published, because it is too difficult to rewrite them as the system becomes better understood. Things are no better with the other standard commodities of development: project plans, schedules, cost estimates, and documentation.
Jonathan Edwards, The Currency of Development

Jonathan is trying hard to build mechanical ways of getting teams to work together. Have a look at his ideas: he's an original thinker. I'm interested in a slightly different take on the same problem. As he puts it, "They are obsolete the day they are published, because it is too difficult to rewrite them as the system becomes better understood."

How do we make it easy to rewrite functional specifications? Some cultures try to solve the problem with command-and-control ("thou shalt not make a code change without an accompanying tech spec").

What I've observed is that all the information we want is out there in emails, PowerPoint decks, screen shots, and documents. And that's just the stuff produced by customers/analysts/product managers. What about the comments in the source code and the source code control system that describe how the changes close a specific bug or implementa specific feature?

Everything's fragmented and gets more and more unwieldy as projects move forward.

Using examples as the central communication idea is just part of the solution. We need to make it easy to write examples and read them. We need to track the history of changes. And we need to tie the examples closely to tasks and releases.



Comments on “Fully Engaged by Example:

<< Home
Reg Braithwaite

Recent Writing
Homoiconic Technical Writing / raganwald.posterous.com

What I‘ve Learned From Failure / Kestrels, Quirky Birds, and Hopeless Egocentricity

rewrite_rails / andand / unfold.rb / string_to_proc.rb / dsl_and_let.rb / comprehension.rb / lazy_lists.rb

IS-STRICTLY-EQUIVALENT-TO-A / Spaghetti-Western Coding / Golf is a good program spoiled / Programming conventions as signals / Not all functions should be object methods

The Not So Big Software Design / Writing programs for people to read / Why Why Functional Programming Matters Matters / But Y would I want to do a thing like this?

The single most important thing you must do to improve your programming career / The Naïve Approach to Hiring People / No Disrespect / Take control of your interview / Three tips for getting a job through a recruiter / My favourite interview question

Exception Handling in Software Development / What if powerful languages and idioms only work for small teams? / Bricks / Which theory fits the evidence? / Still failing, still learning / What I’ve learned from failure

The unary ampersand in Ruby / (1..100).inject(&:+) / The challenge of teaching yourself a programming language / The significance of the meta-circular interpreter / Block-Structured Javascript / Haskell, Ruby and Infinity / Closures and Higher-Order Functions

Why Apple is more expensive than Amazon / Why we are the biggest obstacles to our own growth / Is software the documentation of business process mistakes? / We have lost control of the apparatus / What I’ve Learned From Sales I, II, III

The Narcissism of Small Code Differences / Billy Martin’s Technique for Managing his Manager / Three stories about The Tao / Programming Language Stories / Why You Need a Degree to Work For BigCo

06/04 / 07/04 / 08/04 / 09/04 / 10/04 / 11/04 / 12/04 / 01/05 / 02/05 / 03/05 / 04/05 / 06/05 / 07/05 / 08/05 / 09/05 / 10/05 / 11/05 / 01/06 / 02/06 / 03/06 / 04/06 / 05/06 / 06/06 / 07/06 / 08/06 / 09/06 / 10/06 / 11/06 / 12/06 / 01/07 / 02/07 / 03/07 / 04/07 / 05/07 / 06/07 / 07/07 / 08/07 / 09/07 / 10/07 / 11/07 / 12/07 / 01/08 / 02/08 / 03/08 / 04/08 / 05/08 / 06/08 / 07/08 /