Tag Archives: communication

It’s official…specs are “bad”

Posted on by
Reply

…according to Linus Torvalds. I have to chime in on Linus’ newsgroup posting and the attendent buzz it sparked on the net this week (and on the Linux Kernel mailing list). Linus stated:

So there’s two MAJOR reasons to avoid specs:
– they’re dangerously wrong. Reality is different, and anybody who thinks specs matter over reality should get out of kernel programming NOW. When reality and specs clash, the spec has zero meaning. Zilch. Nada. None.
It’s like real science: if you have a theory that doesn’t match experiments, it doesn’t matter _how_ much you like that theory. It’s wrong. You can use it as an approximation, but you MUST keep in mind that it’s an approximation.
Specs have an inevitably tendency to try to introduce abstractions levels and wording and documentation policies that make sense for a written spec. Trying to implement actual code off the spec leads to the code looking and working like CRAP.

He went on to conclude:

“But the spec says …” is pretty much always a sign of somebody who has just blocked out the fact that some device doesn’t. So don’t talk about specs. Talk about working code that is _readable_ and _works_. There’s an absolutely mindbogglingly huge difference between the two.

This posting launched an onslaught of discussion. Linus is right. Reality always differs from a specification of how software is supposed to behave. That’s a reflection on how difficult it is to write precise specifications of behavior and on how many decisions during implementation are left open. Still, I’m not willing to say “no specs, ever” even though I’m a signer of the Agile Manifesto and on the board of the Agile Alliance. We need to get better at recognizing what types of descriptions do add value and under what circumstances. And become more aware of when and where precision is needed (and when it drags us down).

Linus points out that specs often introduce abstractions and concepts that shouldn’t be directly implemented in code. I never expect to directly translate what someone writes into code without using my brain. I design and think before and during and after coding realizing that nothing substitutes for testing/proving out a design and implementation against the real environment it works in.

But that doesn’t mean specs have no value. Working, readable code isn’t the only thing that matters. It matters very much in the short and long term. But try understanding design rationale by just reading code. Or reading the test code. It’s difficult, if not impossible. I find value in design documentation that explains the tricky bits. This type of documentation is especially valuable when those coding aren’t going to hang around to offer explanations.

A spec is an approximation of what is desired. I certainly don’t expect it to tell me everything. There can be enormous value in writing descriptions of what software should do, especially when it is important to communicate design parameters and system behaviors instead of just providing an implementation. Most developers aren’t good at writing specs, let alone descriptions/discussions about their code and design choices. But that doesn’t mean they should stop writing them and resort to “organic code growth” in every situation. A firm believer in agile practices, I do’t insist in writing merely for fun or because it is expected. But if I need a spec, I write it. And if doesn’t reflect reality or is misunderstood, I change it if there is value in keeping it up to date. There may not be. And if that’s the case, I don’t update it. It depends on the project and the need. It helps if I write these descriptions for someone who wants to read them (and will actually use it rather than toss it aside). I’ve got to know my audience. That often takes experimentation. Maybe I need to include sample prototype code in addition to design notes/models/sketches. Maybe I don’t. Communicating ideas to a diverse audience is especially hard. But specs aren’t the problem. It’s that effectively communicating how something works or should work is more difficult than cutting code. I prefer working code over piles of outdated, difficult diagrams and explanations. But that doesn’t duck the issue. Specs aren’t inherently bad. Most spec writers would rather be doing something else. And that is a problem.

Exactly what do you mean?

Posted on by
Reply

I spent the past week at the Agile 2005 software conference. What an amazing conference and inspiring group of people! I spent some time with Lynn Miller from Alias who presented a report about how her companysuccessfully integrated User Centered Design (or UCD) with agile XP (Extreme Programming) practices. Lynn is the lead interaction designer on an innovative product called AliasSketchBook Pro. As an interaction designer, Lynn gathers customer information and defines and refines user features through prototyping and customer feedback. Lynn then feeds her designs to the development team who develop production quality code in month long “sprints”. At Alias, interaction designers work in tight collaboration with the development team, feeding them just-in-time interaction designs. According to Lynn, this is pretty unusual. Most companies do interaction design in all in one big lump before doing any software development. At Alias, interaction design is done monthly increments, just like the code. Each coding sprint is fed by features defined by the interaction designers who worked on them during the previous month. Skeptics in Lynn’s field don’t believe that usability design can be done this way without sacrificing quality. Alias’ success story challenges these assumptions.

As an interaction designer Lynn isn’t up on the latest agile jargon. So for the first couple of days at the conference she was puzzled when she heard stories about how other agile teams had trouble identifying and working with the “customer” who defined “user stories” that the team implements. To Lynn’s and most people outside the agile community, customers are people who purchase products or services. How could you co-locate the “customer” with a development team? Don’t companies have many customers? What exactly was the problem some XPers were having? Only after a Lynn realized that XP defines customer as “an informed expert who clarifies requirements for an XP team” did her confusion evaporate. An XP customer isn’t necessarily an end user or purchaser of a product. Lynn plays the role of “customer” for her XP development team when she designs features. I agree with Lynn, the definition of an XP customer is confusing.

Lesson learned: Agilists who communicate with others outside their own community need to be aware that jargon is confusing. When someone looks puzzled it may be because they don’t share your context. Bridge this gap by asking a newcomer what’s unclear. Then take the time to decode insider jargon for them. You’ll learn something about what they do and how they think in the process.

I discussed with Lynn and Jeff Patton (another talented user-centered designer)what we each mean by “design”. To me, a software designer, design means creating a model of interacting software objects that are implemented in code. Interaction designers use a raft of techniques ranging from contextual inquiry (to understand the users’ work environment), to user-centered design (to cluster tasks and identify user categories), to interaction and user interface design. All these activities to an interaction designer are “design”. It was pretty easy to understand our different views and see how they dovetailed into an overall system design process. I don’t think we should come up with an unambiguous definitios for our various activities. Besides being unrealistic, we’d all have to start speaking design Esperanto which wouldn’t be a good thing. But I learned something. When you don’t understand what I mean, it is my problem not yours. As a good communicator I should try to bridge my ideas into your context. And when you don’t understand what I’m saying, please ask, “What do you mean by that?”