Human sacrifice, dogs and cats living together… mass hysteria!

A product owner and his developer

What can we learn from Dr. Peter Venkman about the Agile development process? It’s true that Venkman was the less technical member of his team. Clearly Dr. Egon Spengler was the blue-sky researcher while Dr. Ray Stantz was the practical engineer.  But Venkman brought a lot to the table: Charm, business acumen, and the ability to spot an opportunity. In short, Venkman was the product manager.

Egon and Ray focused on arcane reference books and ecoplasmic gadgets. It was Venkman first used their technology to get results in the marketplace—or at least meet girls. Venkman was usually critical of Egon’s and Ray’s “out of the box” ideas but once won over Venkman stood behind his team and rallied them when the chips were down (as when Gozer the Destroyer took the form of the Stay-Puft Marshmallow Man).

Perhaps Ghost Busters is not a textbook example of product management in action but it’s a funny movie and I’ve worked with far less amusing product managers than Bill Murray’s lovable but obnoxious Venkman.

For all his faults Venkman obeyed the 4th principle in the Agile Manifesto:

Business people and developers must work 
together daily throughout the project.

Venkman did not separate himself from his team:

  • He lived in the Ghost Busters HQ (Hook and Ladder 8 ) with Egon and Ray.
  • He took his turn driving the ambulance that served as the Ectomobile (Ecto-1).
  • He even wore the overalls and shouldered a Proton Pack.

Clearly Venkman, Egon, and Ray worked together daily as equals on each project, whether it was ridding a fancy hotel of a noisy poltergeist or cleaning ectoplasm off a hapless victim.

Too often in semi-Agile development processes product management (the business people) function as the boss. They make the decisions. They are the “decider guys” stepping into the problem space for a moment, asking for the summary, and making a quick decision without context or technical expertise (like Walter Peck from Environmental Protection who demands that the Ghost Busters shutdown their “storage facility” and inadvertently releases hundreds of ghosts into Manhattan).

The problem here is that software development is a complex, subtle, and sophisticated problem. It doesn’t sit well with summaries and snap decisions. To really make a good software product decision you have to get into the details. You don’t have to be a programmer but you do have to live with one. Any complex, subtle, sophisticated process benefits tremendously from people who work so closely together they know each other’s strengths and compensate for each other’s weaknesses.

To ensure the cats and dogs are living together I recommend the following four “Make Sures” (as usual based on the bitter pill of experience):

  1. Make sure the product owners (product managers, business people, what ever you call them) sit with the engineers. It’s good if they eat lunch with them and go out for beers once a week.
  2. Make sure the product owners and engineers understand that they are all pigs. The product owners are not “management” and the engineers are not “labor”. This means product owners must participate in the development process in real time.
  3. Make sure the roles and responsibilities of the product owners and development leads are clear. PO’s own the backlog and priority. DLs own the sprint backlog and technical strategy.
  4. Make sure the team makes all decisions though rigorous debate. There is always a business trade off and a technical trade off that has to be resolved—If not you’re not innovating. Software development is not a democracy and everyone does not have to agree. But the best path, not the most obvious one, has be discovered.

Improving Your Whuffie with Agile

Whuffie Burn Up Story Point Burn Down Chart

Virtual currency like Cory Doctorow’s concept of Whuffie will probably replace real money in the next 100 years. Maybe sooner with the way our current economic crisis is going. Once all the hard currency in the world is spent it’s Gresham’s law FTW!

You can get a head start by using Agile development principles to min-max your Whuffie earning potential.

Cory shows us how in his seminal book Down and Out in the Magic Kingdom. (Released under a creative commons license.)

I’m not sure if Cory meant to illustrate the principles or Agile development or he just stumbled into them. Since principles are laws of nature that exist independently of people I like to think that Cory was just observing how collaborative projects tend to take longer than expected or turn into epic failures. Some truths are self-evident as the founding fathers liked to say.

In Down and Out the protagonists are trying to quickly refurbish Disney’s Haunted Mansion with cool new robotic effects. They ask the head Imagineer (Still the coolest job title in the world!) how long it will take:

“Okay, so tell me, if we came to you with this plan and asked you to pull together a production schedule — one that didn’t have any review, just take the idea and run with it — and then pull it off, how long would it take you to execute it?”

Lil smiled primly. She’d dealt with Imagineering before.

“About five years,” he said, almost instantly.

Our heroes don’t have five years. A rival team is updating the Hall of Presidents with leet virtual reality spam in just a matter of weeks. So our plucky protagonists demand an explanation:

“Five years?” I squawked. “Why five years? Debra’s people overhauled the Hall in a month!”

“Oh, wait,” he said. “No review at all?”

“No review. Just come up with the best way you can to do this, and do it. And we can provide you with unlimited, skilled labor, three shifts around the clock.”

He rolled his eyes back and ticked off days on his fingers while muttering under his breath. He was a tall, thin man with a shock of curly dark hair that he smoothed unconsciously with surprisingly stubby fingers while he thought.

“About eight weeks,” he said. “Barring accidents, assuming off-the-shelf parts, unlimited labor, capable management, material availability. . .” He trailed off again, and his short fingers waggled as he pulled up a HUD and started making a list.

Five years? Eight weeks? Our heroes are perplexed. It seems outside the realm of sanity that a project could take either Five years or eight weeks. (But not if you think about Windows Vista or Apple’s System 7.)

“Wait,” Lil said, alarmed. “How do you get from five years to eight weeks?”

Now it was my turn to smirk. I’d seen how Imagineering worked when they were on their own, building prototypes and conceptual mockups — I knew that the real bottleneck was the constant review and revisions, the ever-fluctuating groupmind consensus of the ad-hoc that commissioned their work.

Suneep looked sheepish. “Well, if all I have to do is satisfy myself that my plans are good and my buildings won’t fall down, I can make it happen very fast. Of course, my plans aren’t perfect. Sometimes, I’ll be halfway through a project when someone suggests a new flourish or approach that makes the whole thing immeasurably better. Then it’s back to the drawing board. . . So I stay at the drawing board for a long time at the start, get feedback from other Imagineers, from the ad-hocs, from focus groups and the Net. Then we do reviews at every stage of construction, check to see if anyone has had a great idea we haven’t thought of and incorporate it, sometimes rolling back the work.

It’s interruptions that add months and even years to a schedule. Corry is not making this stuff up.

An Agile process like SCRUM recognizes this fact and uses the concept of the sprint to create a bubble of focus in an ocean of distractions. During a sprint nothing should change—if something does change (new business reality, a framework that doesn’t work as advertised) the sprint is broken. Sprints are kept short so that change can be accommodated in efficient chunks. Corry is simply pointing out why sprints lead to faster development cycles than non-Agile processes.

A few things are interesting to note:

  • The 12 principles of the Agile Manifesto don’t talk about sprints. The principle of time-boxing a problem seems to be missing. SCRUM and other Agile methods inspired by automotive process management married the idea of sprints or locked iterations to Agile.
  • In Corry’s book the Imagineers fall weeks behind schedule because they can’t handle their newfound freedom from stakeholder feedback. I’m pretty sure it’s because our heroes are too busy struggling through their own character driven plot to act as product owners and keep the Imagineers focused.
  • There is a big difference between stakeholder feedback (changing requirements) and product owner feedback (understanding requirements). SCRUM groks this. The Agile manifesto hints at it.

Using an Agile/SCRUM process to develop your projects enables you to deliver on time while incorporating changes. The net-effect is a dramatic increase in your Whuffie. You might as well start banking it now 🙂

The Shorter Timescale

Eternity (Sprints Not Drawn To Scale)

I’m reading a very scary book right now: Heidegger and a Hippo Walk Through Those Pearly Gates. It’s a funny and informative look at how philosophers and religious thinkers deal with death. I don’t want to be a spoiler but the basic message of the book is that most people live in denial of their own mortality and most philosophers are trying to wake them up. Them being us.

This is especially true in software development. Any experienced engineer looking at a 6-12 month project plan will tell you there is a lot of denial going on. I don’t want to sound overly melodramatic but the 3rd Principle from the Agile Manifesto

Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.

…is all about waking up and getting out of denial.

I covered the idea of working software in a previous blog post but “preference to the shorter timescale” idea deserves some focused attention all on it’s own.

If you live life to a Tim McGraw sound track then you don’t waste a lot of time on planning or doing things that are simply not going to happen. The idea of a preference for shorter timescales come from the principle that risk grows with distance into the future.

This principle doesn’t mean you shouldn’t dream big! I’ve met many engineers who tell me “Agile is only for minor tweaks, not big initiatives.” (No I won’t name names but I dare you guys to a blog war!) Your backlog should be as big as forever. It’s just that you plan and sprint for what you can achieve as a human mortal. Zeus and Hera can execute a 12 month plan with a waterfall process–Agile is not for immortals.

I like 2 week sprints (with one week of planning in between) for three reasons:

  1. It’s been my experience that (most) human mortals only have vague capacities for planning and managing large chunks of future time. Today, tomorrow, Next week are  cool. We live in a bubble of now that trails 1-2 weeks behind and runs 1-2 weeks ahead.
  2. Engineers (and artists) are mostly monochrons. (Almost everyone else tend to be polychrons.) It’s part of the self selection process that leads people down the road of life to end up either alone in front of a computer (or piano or canvas) or in a group running around the planet making noise. Maybe it’s all due to Asperger’s Syndrome but the creative process seems to require that we focus on doing one thing at a time for a fixed period of time in a repeatable cycle.
  3. Engineers (and artists) get lost in their work (the music of the spheres as it were) and lose track of time. Short sprints mean they can’t go too far astray before they check in with home base! Once an brilliant engineer told me it took a month to fix an ad server bug because he first had to rewrite Math.c. Good thing I checked in when I did or he might have rewritten all of UNIX!

So if we end up working together I will ask you to think in short increments that give us plenty of time to capitalize on the future 🙂

True Working-ness

A Bird in the Hand

Last week I presented to my team at Lime Wire Agile and Scrum in all it’s most excellent glory. Jason Herskowitz, Lime Wire’s VP of Product Management, and I ran though all the major Agile elements and vocabulary words. The best part of the presentation was questions asked by developers, testers, system admins, product managers, and even a couple of chickens. Many of these guys and gals have been the victims of bad Agile programs. It seems easy to play the Agile game but it isn’t. The most critical path to successful Agile isn’t to follow all the rules–it’s to follow all the principles.

The Agile Manifesto’s 3rd principle, Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale, seems to be often ignored. You can not really ignore a principle. A true principle is a law of nature, like gravity or the axioms of geometry. If you ignore the principle of gravity you’re going to get hurt. If you ignore the principles of Agile your project is going to fail.

I don’t know why the delivery of working software is often left out of the plan. Perhaps it’s that to recognize the truth of this principle requires more than just a thin patina of Agile paint on a waterfall process. Most Bagile (Bad Agile) processes do not understand that a milestone without working software delivered is a milestone not met. In Bagile working software is mutated into “ready for QA” or “all P1 bugs closed” or “works on my machine”.

I’m not taking an extreme view of working software! It’s just that “done” should mean “nothing more to do!” I’ve lived through the bitter experience of discovering that done doesn’t mean working software. Nothing is more discouraging than having to wait weeks for a so-called completed project to be ready for release.

If you think about it, delivering working software in this complex world of clouds, grids, restful APIs, and P2P networks, is daunting. It may even feel wasteful to go though all the effort to get the components integrated and tested every couple of weeks.

But true working-ness means you can get feedback before every iteration from actual flesh and blood users. Feedback like this is invaluable to avoid wasted effort.

True working-ness means you can focus on the future and get rational priorities for your backlog with each sprint.

True working-ness means if you want to go on vacation, you leave things in a good state and others can pick it up while you are gone.

True working-ness means true achievement. It’s pretty hard to make lasting, solid achievements in general, but delivering working software frequently means you have made a concrete difference in the life of your users today.

There is a 14th century English saying that taught me the same the principle as a kid: “A bird in the hand is worth two in the bush.”

Mac OS 3: User Center Design Exemplar

I nearly lost all my data a couple of weeks ago. Actually, I was in no danger at all of losing my data but the terribad UI of Apple’s Time Machine and Time Capsule made me think I did! Apple’s backup solution is like a good looking school yard bully with a hidden inferiority complex.

I used to back up everything manually and it was messy. To be fair Apple seemed to conserve all that backup mess with the Time Capsule wireless base station/terabyte network drive and its slick Time Machine backup application. It just seemed to work: No settings, no maintenance, no hunting for the disk with the 3rd season of Buffy on it.

On the rare occasion when I did need a missing or deleted file Time Machine made it easy, and entertaining, to find (nothing like zooming back in time to give lulz).

One evening last week my MacBook Pro died and upon restart got stuck at the kernel panic screen. I took it Tek Serve in NYC (where they are a million time smarter than Apple’s Genius Bar) and learned that a fresh re-install of Mac OS X was the solution.

To make a long story short, when I connected my revived MacBook Pro to Time Capsule it restored a backup from 4 months ago! That’s a generation in Internet years! Also it took over 12 hours! I was aghast!

With grim determination I started the whole process over and tried to get support from Apple. But nothing helped until I just gave up and accessed Time Machine to confirm it was operational. And lo and behold: There was my data from the previous week. Right up to 30 minutes before the kernel panic attack!


Just before I joined Apple I got some coaching from Bruce Tognizzni (I was designing a set of never-to-be-released apps for Letraset back in 1991). Tog explained that good user centered design doesn’t just hide complexity–it enables the user to navigate it. Time Machine and Time Capsule are bad user centered design according to this definition since they are pretty faces and not much more.

I can’t think of any better example of user centered design than the original Mac OS (version 3) and apps like MacPaint and MacWrite. And since you can’t run it anymore (but you can see screen shots at the Vintage Mac Museum) I decided to bring the Mac OS 3 back to life in flash. Embedded above is version 0.1 of the Mac OS 3 Flash Sim. It don’t do much but I promise to whittle away at it as time permits. I’ll post the source code shortly as well. Right now you can selected the trash can and pull down the apple menu.

It’s funny but the constrained yet expressive capabilities of the original Mac OS are much more like the user experience of the iPhone and iPod Touch then the current Mac OS X. There is something to be said for the power of limitations.

The Name of the Game is Change


The second principle from the Agile Manifesto is “Welcome changing requirements, even late in development. Agile processes harness change for the customer’s competitive advantage.”

I call this the Product Manager’s dream principle: “I get to change the requirements, even after development has started! Woot!”

First let’s break this principle down and see what it really means and then let’s talk about how to deal with it.

There are 4 ideas embedded in the PM’s dream:

  1. Welcoming changing requirements in general
  2. Welcoming changing requirements even late in development
  3. Harnessing change
  4. Customer’s competitive advantage

These ideas come from the grim realization that requirements are going to change, at any stage of the development process, and there isn’t a damn thing you or any process can do about it. We can pretend that we have control over change. We can ask business owners and product managers to sign an iron-clad contract but Mother Nature and Murphy’s Law are not going to stop working on our plans.

Given that change is inevitable we can either hate it or love it or just deal. If this principle was written from the hating change POV it would read “Abhor changing requirements, especially late in development…” On the other hand if the authors of the Agile Manifesto loved change the principle would have read “Encourage changing requirements, the later the better…”

“Welcoming changing requirements” is a positive way to deal with a problematic issue in the same way that many cultures have a tradition of adopting strangers. It’s a smart coping mechanism and recognition that shit happens.

Why do Agilists welcome change and not run the other way and lock the door? Because they are confident that Agile process and policies are setup to withstand change. They have accounted for change in the Agile process and thus change is not going to do much damage to the overall big picture.

Agilists also recognize, according to this principle, that they can “harness change”. Agilists can guide change instead of being driven by it. That’s a pretty tall order but with the right process, one that assumes the inevitable, Agilists take advantage of the opportunities that change creates. Change is where true competitive advantage comes from! Not from a carefully designed, well executed plan, but from a process that gives customers the chance to quickly capitalize on changing market conditions. Wiggle room beats precision any day of the week.

Stephen Jay Gould once wrote about how his interest in fossilized snails, from which he would derive many insights about evolution, came about completely by accident. Gould spent his life discovering and teaching how random events lead to advantages that life is able to exploit. That’s agility right there.

Working with Niles Eldredge, Gould popularized the theory that evolution works in cataclysms called punctuated equilibrium: Short periods of sudden change separated by long periods of relative calm. Agilists see a lot of punctuated equilibrium in software development. Everything in the project is going along as planned and then WAMMO! The market changes, a bug appears, or a forgotten requirement emerges! (This is in well run organizations. In poorly run organizations the change is constant and internally generated.)

OK, now that I have accepted change how do I deal with it? Each school of Agile development from XP to SCRUM has different foci for dealing with change. I’ve seen five patterns emerge that successfully welcome change (but I’d love to hear about others):

  1. Time boxing: Limit the amount of time you spend on any one task so that the cost of change isn’t devastatingly high.
  2. Locked iterations: Restrict change to outside development cycles. Once a dev iteration is started ignore change until victory can be declared. If you really must change requirements in the middle of an iteration stop and re-plan.
  3. JIT planning: Plan as little as possible and as late into the project as possible.
  4. Light design and documentation: Waste as little time as possible on design and documentation as it’s all going to change anyway.
  5. Measure and analyze: Don’t act on assumptions or intuition. Do what the data tells you to avoid surprises.

These solutions in isolation create as many problems as they solve. But when used together in a well thought out and integrated process they create a flexible fabric that can capture the energy of change and use it to gain an advantage. This is hard to do, not because it’s complex, but because many engineers (and normal people too) are uncomfortable with change. One strategy that helps people surf the chaos is to keep a central vision in place with a general roadmap of how to get there. As long as the vision is stable then change is the process of getting there.

Our Highest Priority

Labor is greater than money

The first principle of the Agile Manifesto is “Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.”

Easier said than done 🙂

This principle is deceptively simple and simply radical. I don’t believe it’s an accident that it’s the first principle and it’s first 3 words ensure that what we pay it detailed attention.

So let’s pick it apart!

There are five major ideas embedded inside this 16 word sentence:

  1. Highest Priority
  2. Customer Satisfaction
  3. Early Delivery
  4. Continuous Delivery
  5. Valuable Software

All five of these ideas deserve a blog post or two (the highest praise one can give in the 21st century). But a paragraph each will have to do.

To have a “highest priority” is not a foregone conclusion. Usually you have competing priorities. The classic problem with software development priorities is expressed in the consultant’s conundrum:

Fast, cheap, or good — Pick any two!

The consultant’s conundrum has no “highest priority” and thus an impossible problem to resolve. I’m going to tell you a secret. No matter what the consultant (or Jakob Neilsen) says, you can’t pick all three, or even any two. You can only pick one priority. This is the first principle of agile development and the lack of a single highest priority is the root cause of why projects fail.

To focus on “customer satisfaction” is another tragically overlooked value in the real world. Most business, except the ones that succeed for the long term, focus on everything but happy customers. Even though really smart people write books like Patricia Seybold’s, revenue or awards or downloads are still made into objectives in and of themselves. Another secret: SUSTAINABLE REVENUE FOLLOWS CUSTOMER SATISFACTION! (Sorry for the caps–my shift key got stuck.)

The third and forth ideas, “Early Delivery” and “Continuous Delivery”, are difficult to do because they go against many humans’ natures. Some of us naturally crave feedback and offer up unfinished works for critical review early and often. But that type of human seems not to get into software development. It’s the lonely author, or lonely blogger,  who seems to dominate our industry. He wants to knock the socks off his audience so he waits until every thing is done before revealing his magnum opus to the world. This behavior in a business context is rationalized by the idea that you only get one chance to make a first impression. I feel my shift key being to stick as I prepare to refute this idea–but I will resist shouting in type because of the overwhelming evidence supporting early and continuous delivery: Microsoft, Google, Adobe, Apple, Salesforce. When these companies (and any other tech companies) are successful, it’s when they release incrementally and improve over time guided by customer feedback. When these companies fail, it’s when they hold off for the big bang.

The final idea of the first principle of the Agile Manifesto is the hardest to define. What is “Valuable Software”? What is value? The article on Value (economics) is messy and ultimately not helpful. Like truth, value is subjective and only understood when time and multiple perspectives are integrated. So let us go back the classic definition and say that valuable software is that which “saves labor” (which leaves out gaming and entertainment, but I consider walking away from my computer a form of labor).

If the software you are building does not “save labor” then perhaps you shouldn’t be creating it. I’m serious. There is plenty of software out there that is not valuable by this definition. Yes, I’m thinking of you MS Project! At the end of the day software is about automation and by that I mean the automation of labor.

To me, and many others, the Agile principles are not a silver bullet to cure all the ills of software development. They are a recognition that the software development process is not separate from software being produced. A product that is not valuable can not benefit from Agile development anymore than quackery can benefit from healthcare reform. Our highest is priority is not to make it fast, cheap, or good. Our highest priority is to make it valuable.

Circular Logic in Project Management

Straight line or Circle?

Listening to one of my favorite public radio programs (The World) while carting the kids around this weekend I heard about an interesting study by the Max Planck Institute for Biological Cybernetics. A team of biocyberneticists wanted to find out how well people navigated. They hired a bunch of hikers, gave them each a GPS, and one simple instruction: Go straight that way.

Tracking the GPS devices from the comfort of the lab the researchers discovered that people don’t navigate so well on cloudy days or dark nights. Without an external frame of reference, like the sun or a mountaintop, people tend to walk in circles. Even people who claim to have a great sense of direction.

After reading more about the study I realized that people don’t tend to walk in circles. People only walk in circles. With out an external reference point the natural human programming is to only go so far, turn around, and go the other way.

And this makes perfect sense. Over millions of years, if an individual strayed out of his natural habitat without a good reason, that individual seldom got to reproduce. Our natural inclination is to stick to our territory, to the known, and within boundaries. Even when we think we are on a new path.

The mind is not exempted from this bit of hard coded behavior. I see it in others and myself all the time. In programming we call this recursion when we mean it and a bug when we don’t. In business it’s know as “once size fits all”, “if it plays in Peoria”, and “if it ain’t broke, don’t fix it.” Actually, I wish the business world had relegated circular thinking to tired old cliches. But insidiously it’s in your MBOs. It’s in you mission statement. It’s in your strat plan. Any goal that isn’t externally verifiable is a carrot on a stick.

The typical recursive program looks like this (pseudo code):

As long as there is data DoIt() will call itself. The data is the external reference point, the mountaintop. Remove the call to GetData(), or if it fails to return false, the function DoIt() will do it forever (or until the stack overflows—which ever comes first).

What is interesting to me is how strong the impulse to think in a circle really is. Many times we ignore the Sun or miss the mountaintop.
I have so many specific examples that I can hardly choose one but this is my favorite: The project is behind schedule so we need to:

  • Add more resources: The team is swamped so adding more should help!
  • Spend more money: More hardware, more consultants, more tools ought to help!
  • Work more hours: We just need find another 12 hours in a week to get back on track!
  • Motivate more: Obviously the team doesn’t understand how critical the project is to the company!

All of those solutions are examples of circular thinking because they seek to resolve the problem with more what the team is already doing.

When a project is late (and the calendar is the ultimate external reference point for any project) you have stop. Break the sprint. Reverse course. Look up for a guiding star that points to true north.

This is what works for me:

  • Shuffle the project’s management: Poor execution usually means one thing—Poor leadership. Good leaders take poor plans and make them successful (or change them until they are successful). Poor leaders complain about the plan, the team’s skills, and the design of the product.
  • Hold the budget: Throwing hardware, consultants, and tools at the project usually just makes it more complex. Sometimes running on a faster CPU will temporarily buy time for your pokey little puppy of an app server. But you’re just making some other project late down the road. You should only spend more budget if you inadequately budgeted beforehand.
  • Work 9-to-5: I know I’m going to get a lot of tech management mad at me but I’ve seen this go on for 20 years. Working 12-hour days just buys you bugs and burn out. You can do it for a short “sprint”, maybe at the end of the project. But you can’t sprint your way out of a hole. The secret here is to make sure the 8-hour days are not interrupted by meetings, fire drills, and shop talk. Engineers shouldn’t go to very many meetings, outside of the daily scrum. They get bored and ask silly questions.
  • Admit it’s not going anywhere: The current team is your greatest resource. They’ve been working on the problem, they know why the project is late, and they feel bad or mad or just resigned. Get their help and really listen to the suggestions. Honesty will get you for free what bonuses can’t buy. The team should be working for long term company success not a short term project bonus.

These techniques are counter-intuitive, and that alone probably means we are on the right track for breaking out of a recursive situation. As you can probably guess I’ve had more than a few projects go circular over the years. In the end there are no quick fixes. When you finally figure out that you are lost the realization doesn’t make the problem go away. It’s usually a long walk home—even when you are on a straight line.

Worst Ever Paragraph in a Technical Doc

I’m working on my Flash game framework. Progress, which I admit is slow, requires a good understanding of the Flash CS4 Component model. I embarked on this project a few weeks ago without realizing 3 things:

  1. The CS4 Component Model is very different from the CS3 model.
  2. There is very little good documentation for CS4 Components.
  3. Flash and CS4 Components have become the step children of Flex and it’s entirely different, incompatible component model.


I’m not sure why the CS3 Component Model had to go. The major change seems to be that CS3 Comps were based on a subclass of MovieClip while CS4 Comps are based on a subclass of Sprite. This change in inheritance has some great technical advantages but even more practical disadvantages.

MovieClip is a heavy weight object with lots of functionality. It’s a great starting point for components because you have all of Flash’s frame-based animation at your command. Sprite is a superclass of MovieClip and hard-coded to a single frame. Sprite is a great idea, since a many elements in a Flash game are static. Using Sprite-based components means less overhead for the Flash engine to grind through. Sprite-based components are less overhead for the programmer too: Since Flash plays any MovieClip by default you don’t need to include frame management code in a CS4 Component.

That’s all good. Here’s the bad:

CS4 Components can not share the same stage with CS3 Components. You have to choose one or the other!

There are 5 less Adobe-authored CS4 Components than CS3. Some of my favorites were not ported to CS4 including Accordion, Tree, and Window. I can still use the original CS3 set of components but not in the same application with CS4 components.


A quick search of FlashDen lists 236 CS3 components and only 51 CS4 components. This means to me Adobe has been doing a poor job of evangelizing the benefits of CS4 Components or that the benefits aren’t worth the effort. Or, as I suspect, all of the above.

CS4 components can be compiled so that their code is hidden. I hate that. I hope I don’t need to argue the open source model here. But someone at adobe should read the Wikipedia entry. I know developers who want to make money from their Flash components probably demanded this feature. I want to grab these follow capitalists by the shoulders, look them square in the eye, and say “There is a better way!” Look to the Perl community! Look to the Ruby community! Look to the PHP community! None of our brothers and sisters are starving there! Hiding your code leads to a lack of adoption, a lack of quality, and the illusion that you can sit on your butt and no longer have to innovate.

For me, the single biggest problem with the CS4 component model is the scarcity of quality documentation. The books and sites devoted to CS3 components are too numerous to mention. I found only one decent article on Adobe’s DevNet about CS4 Components: Creating ActionScript 3.0 components in Flash by Jeff Kamerer. It’s a very comprehensive article, points out many of the problematic design details that need to be considered when authoring CS4 components, but it’s rambling and needs much editing.

In fact it contains one of the worst paragraphs I’ve ever read in years of reading technical documentation:

You’ll find ActionScript metadata throughout all component code: in ActionScript 2.0 and ActionScript 3.0, in Flash and in Flex. ActionScript metadata comes between square brackets. It has a name that is followed by a list of name/value pairs enclosed in parentheses. For example, here is metadata with the name Inspectable and a single name/value pair, defaultValue/Label: [Inspectable(defaultValue="Label")]

Confusing yes?

What the author means to say (and I don’t blame him, I blame the nameless Adobe technical editor who should have fixed this) is that metadata is enclosed in square brackets and defined by a name and a string value or a list of key/value pairs. The example given is the most confusing part of this paragraph: It would be much clearer if a general example was used like [Name(key="value")]. By using a specific example he makes us hunt for the general hidden in the details. The example uses “defaultValue” as the key and confuses us with the word “value” on the left (the value is on the right). By using the string “Label” for the value the example confuses us with a synonym for a name on the right (the name, or key, goes on the left).

Unless I’m so confused I got it wrong.