link

Example isn’t another way to teach, it is the only way to teach.

   --Albert Einstei

I’ve started work on a book, tentatively titled _Driving Projects with Examples: a Handbook for Agile Teams_. All that’s done to date is the Preface.

Two years ago, this would have been about driving projects with tests, but I think the role of examples in projects is larger than that. Also, examples fit more obviously into the whole "individuals and interactions over processes and tools" thing. Examples are something people use to explain themselves to each other. Conversations and learning are more obviously part of the picture.

Because I’m so hot on examples, I’ve put the draft book on a new site, exampler.com. Here’s the book: <www.exampler.com/book/>

(And, rather than "QA", "tester", or even "ECaBian", "exampler" might be a good name for those people on an Agile project that exhibit certain traits more strongly than other team members.)

Some of you practice the style of development I’m documenting - or variants of it. If you do, I want to talk to you, be it on the phone, or via emai, or in person. (I am budgeting travel money to visit worthy sites.) I’m serious about the "handbook" in the title: I want to fill it with tricks, tips, techniques, and stories. The more people I gather them from, the better the book will be.

In this document we show you the Ruby version of the Smalltalk code published in the pink book.

"The quantity of meaning compressed into a small space by algebraic signs, is another circumstance that facilitates the reasonings we are accustomed to carry on by their aid."

• Charles Babbage, quoted in Iverson’s Turing Award Lecture

paulgraham.com/power.html

The first person to write about these issues, as far as I know, was Fred Brooks in the Mythical Man Month. He wrote that programmers seemed to generate about the same amount of code per day regardless of the language. When I first read this in my early twenties, it was a big surprise to me and seemed to have huge implications. It meant that (a) the only way to get software written faster was to use a more succinct language, and (b) someone who took the trouble to do this could leave competitors who didn’t in the dust.

Brooks’ hypothesis, if it’s true, seems to be at the very heart of hacking. In the years since, I’ve paid close attention to any evidence I could get on the question, from formal studies to anecdotes about individual projects. I have seen nothing to contradict him.

…I arrived at the classroom ten minutes before the lecture began. I was worried that there wouldn’t be any seats left, but I discovered one at the fourth row from the front so I hurried over and sat down. The classroom, which can hold around 200 people, filled up almost instantly. By the time I entered the room, Mr. Miyamoto was already sitting in a chair next to the blackboard.

Since Miyamoto was apparently too busy to make any special preparations for the event, it was decided to move from a traditional lecture format to a more informal discussion. To start off things, the instructor in charge discussed CERO [the Japanese game rating system], age restrictions, GTA, Kakuto Chojin, and other topics related to game regulation.

And then Miyamoto stepped up to the mike. Applause…

www.video-fenky.com/features/miyamoto.html

 "I can't do all that stuff you say I should do, but how do I handle the situation ..."
  The response:
  -- IT WON'T WORK HERE doesn't work here.

 I'm developing an executive dashboard, and I haven't been satisfied
 with the business graphics that are widely available
 (e.g. gauges, dials, stoplights). I decided to make a "Zen" version
 of a KPI status indicator, using as little color as possible,
 and incorporating E.T's innovative "Spark Line" metaphor for display
 of trends. The graphic below shows the proposed KPI display across
 the top of a browser screen with a descriptive example in the middle.
 Any feedback would be wonderful!

 Comments: Because of complex KPI names (e.g. This Week versus Last Week
 Sales (All Divisions), KPIs were labeled with Roman numerals.
 Balloon help could display the KPI name when the cursor brushes the
 KPI indicator.

link

Both of these images are wrong. Hacking and painting have a lot in common. In fact, of all the different types of people I’ve known, hackers and painters are among the most alike. www.paulgraham.com/hp.html

 > Surely, you're not calling design documents you built in the middle
 > of a project "up-front" design?

Let’s talk about "project" and "up-front" for a second.

In the old world I came from, a project had a feedback loop. This feedback loop could be considered to have covered design to unit testing, roughly a period of 6 months to a year on many projects. In other words, I would get feedback on my design 6 months after I made it.

Now let’s enter the fractal nature of XP.

My design to unit test feedback loop is the duration of a card in most cases. In some cases it’s as small as design/refactor/new test/new code/refactor/ (which may be a scope of minutes). In some cases it may be as large as an iteration (after all, we didn’t pick the cards in this iteration at random, we had a plan). It may even have been as large as a release plan.

The difference is that I get my feedback quickly and the design I do at any given stage is as small as it needs to be instead of as large as it can be. But I still do design "up-front". I have a plan before I leave the release meeting. I have a plan before I leave the iteration meeting. I have a plan before I even start refactoring before that first unit test. I have to make the same decisions I would have made in the BDUF, the only difference is that I make them as late as possible. In short, I make them just before I do the task that requires that decision to have been made.

XP is fractal. It’s possible to think about an XP project as a large collection of projects, each small enough to be written on 3*5 cards. And I do design for every one of those projects up front.

• The dealer gives the customer all the chips for this iteration
• Then the customer "shuffles" the cards and lays them down
• As each one is laid down, development uses a different color of chips and places the number of chips that story costs.
• If the customer is okay with it, they then take an equivalent number of chips from their "stack" and place it to the "bet" pile.
• If the customer isn't okay with it, the story can be split (kind of like "double down" in blackjack) and/or cards can be "reshuffled"
• At any time, the customer may "reshuffle"
• When the customer is out of chips and is okay with the current "bets" and card order, the planning session is adjourned

 >An activity that I /do/ still have trouble with, however, is writing.
 > When faced with having to compse anything more substantial than an
 > email response, I feel the fear start to creep in and I get myself all
 > tied in knots.  Even after I start to put some words down, I often
 > find myself getting stuck because the thing isn't flowing and the task
 > of finishing seems overwhelming.

Yup, writers block definitively, as John Roth diagnosed already. But if you’re able to describe it in such flowering detail as above, there’s no need to have it.

 > So on my way home last night (after another frustrating couple of
 > hours trying to get some thoughts on paper), I was thinking about how
 > I could make my prose writing come as easily as my code writing.  I
 > started wondering if I couldn't somehow employ a TDD-like cycle in my
 > writing process.

I am often writing articles with my business partner, who’s<br>especially good at collecting lots of nice stuff on the web. The first thing I have do with the "drafts" I get from him, is to find the<br>structure fitting best to the available data. This is currently donein a Mindmap using freemind (freely available at sf.net, IIRC). For some<br>time I also tried vimoutliner (www.vimoutliner.org) for this, but found that for this process, the two-dimensional display of a mindmap is better suited to my brain.

When the outline is finished, I start to grow the flesh on the bones. That’s relatively easy, as I confine my work strictly to the current paragraph.>

The next step is easy, if I have the time: I let the stuff settle for a few days, then go over it once more and clean up the unbelievable mess I created then. If I don’t have the time, I need to play about two hours nethack, which erases my brain just as well…

So the steps are:

 - data collection
  - gradually by experience
  - by force (coauthor delivery)
 - data organization
   - mindmap
   - outline
 - draft
   - follow the map
   - work local
 - refactor or polish
   - grammar, spelling, rhetoric
   - present line of thought more clearly

I think that there’s a difference between code and prose showing here. You expect your code to give certain results for a given input, and you are free to not care about the implementation at all. With prose, implementation is almost everything. So the cost of providing a "working release" is higher with prose than with code. At least for me.

 >find myself getting stuck because the thing isn't flowing and the task
 >of finishing seems overwhelming.

Writing is like every other kind of art. It is never finished. Feeling better now?

Writing is like dealing with animals. Don’t be afraid of it, and it won’t hurt you.

Your fellow author in pain, S.