Functional specs subvert the hierarchy of nature Matt 15 Mar 2006

45 comments Latest by daan

The other week I got some interesting perspective on the Functional Spec debate from an unlikely source: a comparison of code law and common law.

First, some background: No Functional Spec was the first Getting Real piece of advice ever written here. It’s also the subject of an essay in our new book and Jason addressed it during his Q&A session at SXSW (you can hear near the end of this podcast). Still, it’s one of the more controversial aspects of Getting Real. People argue it’s reckless and that functional specs are a necessity.

So what’s code/common law got to do with it? Here’s a very basic explanation of the legalese: Code law is based on a system of codified written laws. The rules are set and that’s that. Common law, on the other hand, is based on a series of ongoing decisions (like the legal system here in the US).

So we’ve got a rigid system that’s set in stone vs. a flexible one that reacts and responds to real-world situations. Sounds familiar, eh?

The bit that got me thinking was a passage in a book by Alan Watts, a philosopher and writer. In it, he tries to explain why common law is superior:

Common law rests ultimately upon the judge’s intuitive feeling for equity. Every case is unique, and no code or set of fixed principle can provide for every eventuality. The deciding factor is therefore something far more subtle and complex than any formulation of rules can be — the judge’s brain, assisted by precedents and rules. Code law, as well as authoritarian and traditionalist ethics, subverts the hierarchy of nature. It gives greater trust and authority to the relatively crude and rigid structure of verbal rules than to the infinitely more fluid and complex structure of the brain, the organism, and the field in which they live.

There’s some meat in that last line. To whom do you want to give authority? Whom do you trust? In a lot of ways, that’s at the heart of the spec vs. no-spec debate too.

Plug in “spec” for “code law” in that Watts excerpt and you’ll see what I mean. Think about it: When you use a spec, you give your trust and authority to a piece of paper rather than the people on your team. You codify laws. You strip your “judges” of the ability to act on intuitive feelings. There’s no fluidity. There’s no ability to respond, change, and evolve. Heck, let’s go all the way with the comparison: Functional specs subvert the hierarchy of nature in favor of an authoritarian mindset.

Now I admit there are situations where a spec can be helpful. It may soothe a worried client. Your team may be too big to fly without one. Joel Spolsky offers thoughtful pro-spec views in “Painless Functional Specifications - Part 1: Why Bother?” Still, I wonder: How many people need to use specs for the reasons outlined by Joel and how many choose the spec route simply because it provides a safe/less-risk/everyone’s-ass-is-covered path?

If the reason is the latter, that’s a shame. What may seem like the safe choice strips away the possibilities you get from allowing and encouraging evolution — and that’s actually pretty dangerous.

45 comments so far (Jump to latest)

Brad C 15 Mar 06

Of course, here in the US we are not based 100% on common law. The constitution and more specifically the bill of rights serves as the “code law” upon which all common law is based and judged.

Without the “functional spec” of the bill of rights, would you feel as safe going before a judge or being questioned by the police?

Tim Almond 15 Mar 06

The problem is often down to how businesses have to work together.

In the field of basecamp, or working on time and materials, producing something that people can choose or not, functional specifications are less necessary. You offer a service for a monthly fee, and people can take it or leave it. It’s a delivered product that someone can see and alter.

For many people, they are delivering something bespoke. Lots of people are using it who have to be satisfied. Ultimately, lots of thoughts, discussions, meetings and emails are distilled into a functional spec. It is a consistent document that tells every party what the system does.

Also, it is a cover-ass, but you need it. If you’ve done thousands of dollars of work, and are waiting for sign-off, the spec is what was agreed, and what people pay up over. I’ve worked on plenty of non-specified projects, and feature-creep is a big problem with them.

Scott Hurff 15 Mar 06

So my natural question is this — in the course of performing client work, how does one make clear what a Web site or piece of software will look like if there is no overarching, guiding document?

I suppose this is where the one-page story comes in, as mentioned in Getting Real (PDF and posts). But in the end, both parties must sign off on this document. So, in essence, this becomes the spec.

How do you rectify this?

Haacked 15 Mar 06

Not having any sort of spec would equate to a system of common law based on verbal tradition and history. That’s hardly the case here.

Rather there needs to be room for something in between. Not all clients are ready to go to “court” every week to clarify the “law”. Some will, and god bless them.

I’d say rather than a spec, have a functional constitution. At least have the big picture written down, similar to Joel’s perspective. And then try to get customers to understand that it is not the 10 commandmants engraved in stone, but rather a working “living” document.

Good luck with that though, as not all clients will get it.

Piotr Usewicz 15 Mar 06

Hm… I struggle.

Steve R. 15 Mar 06

A small point, from my undergrad Business Law classes - common law is not interpreted by judges quite as ‘whimsically’ as the quote seems to reflect. From “Business Law: Principles, Cases and Policy”, Roszkowski, 4th edition - “Under the common law system, the basic principles of law are set forth in case law, decisions written by judges to resolve specific cases.” Specific, in this case, refers to precedent cases.

Common law gives judges no ‘creativity’ or freedom to acto on intuition - they *must* look at prior cases and then decide what key aspects of *those cases* are at issue.

As I read the above commentary, it appears that judges are perceived to have more flexibility under common law - I would argue that is not the case, they are merely required to dig deeper to find the underlying ‘true principle’ at work from the precedents. Granted, choosing a precedent from the reams of case histories we have is probably close to an art form, but still - I think the point is a valid one.

BTW - Brad C. - I think you hit the nail on the head. I think a fair use of functional spec would be a to-do list (or Ta-da list, better) that had just enough detail to tell you what had to be done, but nothing else. That is just my $.02 - I work projects only for myself, so I am not beholden to a client who may be more concerned with a comfortable, if functionally useless, paper trail.

Rabbit 15 Mar 06

Scott Hurf asked: So my natural question is this — in the course of performing client work, how does one make clear what a Web site or piece of software will look like if there is no overarching, guiding document?

The interface is your overarching “document.” Interface screens with stories are more clear than a document with words and diagrams.

I’ve believed in the interface first for about 2 years now. It works for me.

Alex Bunardzic 15 Mar 06

There are two things that are pertinent here:

1. If I’m not mistaken, 37signals acts from a ‘software nutritionist’ position (I wrote an article about that: http://jooto.com/blog/index.php/2005/11/24/software-caterers-and-software-nutritionists/)

When you engage a customer in a project to build a solution for them, what you’re really interested in is figuring out what goal(s) are they trying to achieve, not *how* are they going to achieve those goals. Functional specs are all about *how*, and as such, tend to muddy the water.

What we usually do is try our best to articulate the *what* and get the customer to sign off on that, and then we take care of the rest (the *how*).

2. It is naive to assume that people despise inefficiency and can’t wait to shed the rigid bureaucratic shackles. One of the main reasons people like to aggregate and organize large workgroups is just so that they can exercise all these code laws. They don’t really care about the common laws, the organic fluidity and all that.

The spontaneous flow is more reserved for the individuals, for the artists, the creators among us.

Christopher Fahey 15 Mar 06

Great analogy. But I don’t think it supports the nobility of your thesis entirely.

Common law is about as “natural” as despotism: It is perfectly “natural” for a small number of people to trample all over the rights of others in order to acheive their objectives, whether or not their objectives are for the good of the people. Historically, despotism has been the most common form of leadership, and it has acheived great successes (Rome)… and great failures (Rome).

Despots do not require laws or contracts to govern their decision making, but they do need something to ensure that things run smoothly in their organizations at the level of detail that doesn’t interest them. Common law is what society has created to fill in the gaps, to allow an organization to make those decisions the despot doesn’t want to make themselves while still ensuring that the despot can make an arbitrary decision any time they please, for good or bad. Coded laws were specifically invented to prevent would-be despots from grabbing powers we don’t want them to have.

Common law works for small, top-down organizations in which the bulk of the people, for whatever reason, have no choice but to trust each other, or the rulership, to make the right decisions. In an ideal democratic hippie organization composed of trustworthy and competent people each with approximately equal powers, common law seems like an agreeable approach to acheiving group objectives. In an organization in which there is any chance that a person can cheat their way to a greater position of power, where an incompetent person can find themselves making important decisions, where an empowered judge can be corrupted, or where the leader can become a fickle tyrant, or even where sometimes people make innocent mistakes, coded laws are still our first and best tool towards preventing and/or fixing problems.

The invention of written law, and more elegantly the Constitution, is generally regarded by historians as unequivocally a Good Thing. For some organizations a functional spec is a kind of Constitution, setting ground rules that we’ve all agreed on.

Jason has described functional specs as a “political document”, to which I say “damn right”. Yes! To me, a functional spec is nothing but a political document (or, more accurately, a legal document). And, much like a Constitution, a functional spec acts as an organization’s principle line of defense to prevent or ameliorate misunderstanding, incompetance, corruption, exploitation, and deception. If your organization (i.e. your team, vendors, and clients) are free of all of these negative qualities, then please have fun living under unwritten common laws. Coded laws don’t prevent these problems, but they help.

For those of us who sometimes have the misfortune to cross paths with such problems and such people, I’ll have my social contract on a peice of paper, thank you.

ML 15 Mar 06

In an organization in which there is any chance that a person can cheat their way to a greater position of power, where an incompetent person can find themselves making important decisions, where an empowered judge can be corrupted, or where the leader can become a fickle tyrant, or even where sometimes people make innocent mistakes, coded laws are still our first and best tool towards preventing and/or fixing problems.

I think you’re onto something here. A lot of this does depend on what kind of organization you’ve got. For us, the Getting Real, no-spec model works great. For others, it probably won’t fly.

When deciding for yourself, it might also be worth considering what kind of organizational model you’re trying to promote. Do you want to treat your team members as cheaters and incompetents?…Or as people who are trustworthy and intelligent? Either way, they just might fulfill your expectations.

Geert 15 Mar 06

I’m with Tim Almond here, for a time & material you could skip specifying the functionalities a system will include but for a fixed price you need that info to come up with your quote and yes … to cover your ass.

Eric Lussier 15 Mar 06

In the end it boils down to accountability.

37signals does not report to anyone. They can basically do what they want. If they screw something up, the users will tell them and they can change it back.

The poor guy from the SXSW clip, stuck in the bowels of Yahoo, needs to report to his boss, who needs to report to his boss. This very fact necessitates a specification or one hell of a lot of trust.

Big company vs Small company.

Accountability vs Freedom

Bureaucracy vs Free love

People should stop worrying about trying to force 37signal methodologies to work for them. Jason & co have constantly said that it may or may not work for you. Do what’s right for your situation.

Try forcing that methodology on yourself.

Ricardo Barrera 15 Mar 06

Actually, in most common law jurisdictions, the relevant legislative body can legislate in “derogation” of the common law—that is, it can pass a “statute” (put in “code” that) which overrules, modifies, controls, or guides the common law applicable in any given case or cause fo action. Most “tort reform” statutes are in derogation of the common law of torts, for example.

Rich Ziade 15 Mar 06

I’m not sure about this analogy.

Common Law is still grounded in rules - they’re statutes passed by a legislature. Judges in common law systems fill the gaps where statutory language falls short. Their decisions, over time, become case precedent - i.e. law as well. It’s well known that case precedent is secondary to the rule of law as handed down by government. A judge cannot override a statu (in theory of course).

So in applying the analogy to func specs, there is still “spec” even in common law. In technology, even a a solid spec is subject to interpretation - which is akin to a judge making a judgment call on some nuanced aspect of the law.

As to the whole func spec debate, imho you simply can’t build a large scale application (“large” as in breadth of requirements, not scalability) without some artifacts that explain what the thing is supposed to be for the constituents involved. Chaos will ensue.

Christopher Fahey 15 Mar 06

Do you want to treat your team members as cheaters and incompetents?

Two responses:

1) It’s not just character flaws we’re talking about here. Miscommunication is also a potential issue, on any team. The bigger the project, the bigger the impact of the miscommunication.
2) You can trust your whole internal team with all your heart and soul, but sometimes a vendor and a client, or two companies/organizations in partnership, simply don’t see eye to eye and at that point it helps to have something on paper. Even if everyone wants the best possible results, everyone wants to minimize their costs and maximize their profits. If both a client and a vendor know that Feature X will be great for the product, but building Feature X will require the vendor to not make a profit, it’s the functional spec that tells both parties that the cost must change.

Phil 15 Mar 06

My initial repulsion to “no functional spec” was due to the ideas presented by Joel Spoolsky and Philip Greenspun’s. I learned that “hire a graphic designer” was step 4, after figuring out the data model, legal transactions, and creating forms.

Things have changed for me:

First of all, I read the book. It helped me put the disconnected ideas into context. Taken as a whole, the process is very elegant and powerful. The Zen-like-quality of the ideas presented is indeed applicable to other areas of life.

Secondly, I started practicing what I read. I actually cracked open Dreamweaver and started designing screens for a small app redesign. No code; just screens. The design process had positive influence on my assumptions about the app.

Third, Philip Greenspun’s process recommends simple, obvious interface early on. Joel’s functional spec is a document of screens when you boil it down. Actual HTML interfaces is just one step further than that. I realized that Getting Real isn’t as radical as I had first concluded.

On a personal note, your comment about trust relates to something I’ve been experiencing in my spiritual life. I’m delighted to find the theme repeated in the work day.

John Hillman 15 Mar 06

There is still a need for functional specs adn they can contain images/screen shots/ flow diagrams ect. No spec is like working with no contract. It’s fine when everything goes OK but as soon as something goes wrong everyone needs to go back and look at the agreement.
I think it’s too simple to say that being flexible makes up for the absence of spec. The spec needs to be defined and agreed but there can be room to mediate within it too. If something in the spec won’t work then all parties can agree and work out whether there will be any impact on the product and on the costings.
I’ve worked on large projects with Specs - they are a pain and they are extra admin BUT you can’t run large teams and large budgets without a degree of accountability on all sides.
Working for themselves 37signals maybe won’t need to spec things too much. Working for a large corp and they might need to define their offering in order to win the work.
I love the idea of less and not over complicating things but sometimes things are complicated and they need a discourse which is also complex and which spells out the detail so that all parties can agree.

Micah 15 Mar 06

Brad C pretty much completely summed up the objection to the No Spec method in the very first post.

one thing i think deserves further comment though is the assertion that a spec robs team members of fluidity and intuition. of course it does! one person’s intuition cannot and must not go straight into a large, complex piece of software. it will, in plain language, bone the project royally.

a spec is not a monolith - change requests are an essential part of a project. they allow the client and the devs to change the course of the project and get that fluidity and intuition into it while still maintaining the ability to keep “i’ll do the feature i think is cool” type decisions out of the product. just say no to committee-designed horses.

Brad 15 Mar 06

I think the entire essence of this getting real thing, particularly as it relates to the ‘no functional spec’ discussion is this:

Only spend your time on activities that bring you closer to your actual goal. Everything else is just noise.

If your goal is a nice, well formatted library of documents that everyone in your company has contributed to and agreed on, well then, get on that functional spec or 2 year projection. But if your goal is an actual product, cut out the things that chew your time and don’t contribute to actually building what you want to build. If you need buy in, make a phone call to the person who makes the decision instead of calling a meeting. Avoid the silly business busyness procrastination that amounts to wasted effort and lost time.

Don’t plan for tomorrow when you have an opportunity to act on today. Worry about tomorrow tomorrow. Stop letting fear inhibit your impulses.

Fear drives many bad decisions. Write a document so we can mitigate risk. Hold a meeting so we can disseminate responsibility. Hold off acting on a impluse until you are sure it is the right direction.

Fuck all that bull shit.

Web apps provide a platform for the build it/fix it/build it/fix it cycle. Get off your ass and do something instead of just talking about doing something. If it sucks, big deal, fix it and make it suck less. If it’s broken, big deal, fix it and make is less broken. If it’s half ass, big deal, fix it and make it less half ass. If it works, Big Deal.

But if you’re really just a belly full of hot air, condemned to a life of mediocrity by your own fear of failure, and you don’t really have the courage to act, and you can spout all the altruisms with the best of them but spend your evenings whining about not having enough time or money or skill, sit down, shut up and move out of the way. You’re just noise. We need less noise.

Rabbit 15 Mar 06

Way to rock’em, Brad. :)

Robert Brewer 15 Mar 06

You might also be interested in reading “The Risk Management of Everything”, which discusses some of the history behind the recent push for authoritarian schemes. You can get it in PDF form from http://www.demos.co.uk/catalogue/riskmanagementofeverythingcatalogue/

Middle Ground 15 Mar 06

Why is it assumed that UI design, info design, and technical design happen serially (placing all of the importance on which comes first?) These processes always take place in parallel everywhere I’ve worked for the last ten years. While clients are eating danish and reviewing the latest round of designs (which are specs in their own right,) everyone else (info/tech/etc.) is working with business managers to iron out the requirements and devise their approach to each set of problems.

No one is starting from scratch here, needing to “think” about how the login should work (or look for that matter.) With the exception of the genuinely original/new features of any app or site, the design, documentation, and development is just another in a series of very similar projects.

The “No spec” concept presumes an awful lot; like designers _can_ 1) code screens, 2) _should_ code screens, 3) aren’t wasting a lot of time in (ahem) Dreamweaver, instead of Photoshop.

Why would I trust information design duties to a “designer” anyway? I’ve tried to task designers since 1999 with designing the UI (instead of the surrounding template) and they primarily balk at the idea.

This whole idea of No Spec only works if you’re dealing with individuals that are smart, have good aesthetic instincts, strong front-end coding skills, and an understanding of how choices on the front-end, impact implementation on the back end.

News flash. Every small company (of seven or less) has a few of these people, or they go bust. So No Spec is a very organic and natural process for them. Every big company has a few of these people too, but they are outnumbered by tens, hundreds, or thousands of others with titles that preclude “the gurus” from working across disciplines. Thus the spec is required to get anything done.

If the 37S team had to manage 100 people, I am certain they would codify their standards, principles, and ideas to ensure the quality of their products was maintained—much like they have done with their book.

Any document serves ONE PURPOSE, to let the people that “get it” explain it to the people that don’t. If everyone on your project “gets it” and are talented, go wild. If you work in the real world, write it down so the dimwits don’t fuck it up.

John Lewis 15 Mar 06

My father gave me some advice when dealing with car mechanics.

He said:

“If you go in and tell them that your radiator is broken, they’ll fix your radiator and charge you $300. Now what if the real problem is a fuse that checks the radiator? You end up with a new radiator and a warning light that still blinks.

What you should do when you visit the mechanic is say ‘My radiator light keeps coming on for some reason. Can you fix it?’ Then the mechanic will check everything from the light to the radiator… and find the fuse isn’t working. The mechanic is happy to do exactly what you tell them, make sure what you tell them is what you want.”

You can see that from a client perspective we are auto mechanics and it’s in their best interest to tell use their ultimate goal and let us sort out how to make that happen.

Sean 15 Mar 06

One great aspect of the common law analogy here is exaclty what a few of the comments have alluded to, that common law isn’t just some whimsically applied rule by a judge. It is based on the collective knowledge and abilities of the judge and the judges who came before him or her.

I remember a very passionate media law professor of mine explaining what makes our judicial system so great and stable. It uses code law, combined with precedent (existing common law), and the issues of a specific case to decide what the best way to proceed is.

I see the same thing with getting real. You have code law, which is all the general principles and knowledge that guides the team as a whole, precedent(existing common law), which is the collective experience and specific knowledge of the team and finally you have the issues of the specific case, which is the specific application, project or whatever you are working on. Collectively these three aspects add up to a much better result, and hoepfully much better software, than any piece of paper could.

Great analogy Matt.

Colin Scroggins 15 Mar 06

Matt: I am not sure this is a great analogy because common and code law are not functional equivalents, and both are required to make the legal system work. I believe that this analogy carries with it some additional implications and dependency between common and code law that you do not intend to be conveyed.

Hrush 15 Mar 06

Ok, there’s a lot of talk here about how this analogy is wrongheaded. If I can try and summarise that point of view and extend the analogy:

* The constitution is the *original* functional spec
* Confronted with a new case, a judge considers all the evidence and the precedents and provides a verdict
* The new case is, in common project parlance, a *change request*

If the above is acceptable, then I think Matt’s analogy is perfectly acceptable. Below is the analogy from a spec and a no-spec perspective:

* Spec = Constitution
* Prototype/Current App = Constitution

Either way, change is change. Change is possible in both situations.

The real question here is: which situation lends itself to easier, faster, cheaper change?

scott 15 Mar 06

well i think we’ve done an excellent job of illustrating why analogies fail on the internet. it’s like asking a group of dendrologists what they think of your forest.

was… was that too subtle?

Hrush 15 Mar 06

Scott — very subtle indeed.

Any thoughts on how analogies on the internet are more prone to failure than analogies in other media?

scott 15 Mar 06

oh man now we’ve progressed from discussing the topic, to discussing the analogy, to discussing the discussion of the analgoy.

i’m guessing that the fact that any information is only a google search away only serves as an encouragement to people who would otherwise accept the analogy, or at least accept that they comprehend the point the analogy was intended to clarify.

unless i’m wrong and matt intended to spark a debate over common law. or uh such as the viability of analogies on the internet.

Martin 15 Mar 06

Sod the analogy.

You’re completely correct when you say that functional specs can be done to death and are usually pointless.

That said, when you’re a) communicating your intent to others, b) communicating your technical solution to a problem, or c) managing expectations with clients who do not have much web background, specs make for common language and shared assumptions.

A two-page project scope document that lists objectives, expected outcomes, assumptions, and resources required is probably all you need for 99% of the work out there, and will likely provide as much common information as people will be comfortable processing.

Dallas Pool 15 Mar 06

I will say one thing hear really quick and then I’ll shut up.

In a small team of 5-20 developers who are all on the same page in terms of the project and vision then yes, you can do away from the functional specifications, the paragraphs of text and requirements and head directly into photoshop and functional mockups….

BUT

If you run a web design company, (which I do), and you have clients coming to you asking you for quotes, time lines, “Can you do X and how much will it cost and when can we launch?” questions…

If I told these clients, “Yes we can do that, but in order to tell you how much it will cost you we have to finish the project, which could be in beta for almost a year… or more… because we basically hit the ground running and all you have to do is pony up the cash and trust us.” …….. Ya, You can see where that is going really quick.

Clients, especially the ones who are USED to working in the functional spec world, *expect* to see functional specs… They demand it. Otherwise, there is nothing (in their eyes) to sign a contract *for*.

So, I would really love to hear how I could turn the getting real philosophy into a practical, functional business model in dealing with outside clients… and not internal projects.

I’ll shut up now :)

Vishi Gondi 15 Mar 06

The code/common law in different from the no spec philosophy.

Instead of one big spec we have a small story/screens doc along with a lot of chronological tickets which are always accessible to the client.

If the tickets are well written there is no trust/mistrust involved.

The only rule is that all tickets should be communicated/accessible to all parties involved.

Shrikant Joshi 16 Mar 06

In the web development field:

I tend to see Functional Specs as a method in the madness that is development.

This post reminds me somewhat about the File upload design post that you uploaded a few days back. What was that if not a sort of a Functional Spec?

To me a Functional Spec is something that describes how a software/application/feature will ‘function’. It is more of a document (presentation, actually, if you ask me.) outlining the flow of steps from the user perspective. A step-by-step guide to how the user will perceive it happen.

After all, you do it for the users, and no less.

Regards,
Shri.

Aaron Blohowiak 16 Mar 06

Functional Specs do not subvert the hierarchy of nature - they just reflect the more pastoral aspects of nature rather than the carnivorous.

Travis 16 Mar 06

I think that the point I will take from this discussion is that There Is More Than One Way To Do It (tm), but that one should always be cognizant that at times a particular method will be helpful, and at other times problematic.

To analogize:

A functional spec can be a stepping stone, or it can be a stumbling block. On the path to our goal, we must choose wisely where to step, and not compulsively follow the same methods always.

However, this requires both awareness of options and the freedom to choose. I think that this discussion has raised the awareness of many, and will hopefully aid them in their choices.

ML 16 Mar 06

A two-page project scope document that lists objectives, expected outcomes, assumptions, and resources required is probably all you need for 99% of the work out there, and will likely provide as much common information as people will be comfortable processing.

Good point. Even if you can’t abandon specs, maybe you can at least take some steps in the direction of Getting Real. What’s the leanest spec you can get away with? How can you spend less time on paperwork and more time on building something real? Everyone has their own situation to deal with and we realize that. We’re just advocating ya minimize the talking phase as much as possible and get into the doing phase as soon as you can.

Shawn Smith 16 Mar 06

Functional Specs for the sake of themselves, or just because they’ve always been done, or because you have a Business Analyst on staff who needs something to do are all too common.

Still, there are a few things in my experience that determine just how much spec documentation a project needs:


  1. Complexity - If it takes more than one brain to contain the thing, then you need to transmit and receive (transmit what’s in your brain and receive what’s in other people’s brains). Complexity creates dependencies (you need to know x in order to do y). Complexity often means there are a lot of ‘if’ statements and alternate or conditional scenarios.

  2. Bulletproofness - If a mistake will result in loss of life, liberty or a lot of money, then risks need to be eliminated (not just mitigated) and butts need to be covered. For one thing, this means it’s complex (see previous point). If you’re designing an aircraft or a nuclear plant, then documentation helps you make sure you build and test every nook and cranny of the thing.

  3. Team Distribution - The more distributed your team is across space and time, the more dilligent and thorough you need to be about documenting things. If you’re designing something that’s going to be built six months from now by some unknown team of people halfway around the world, then your design had better be thorough. Your documentation could reside in the code itself, but it needs to exist. Of course, it’s in the best interest of everyone to minimize the space and time between team members.

  4. The Client - People don’t like to spend money without knowing what they’re getting for it. It’s cheaper to revise (or scrap) a product that’s still on paper than after it’s built. Of course, rough prototypes can sometimes replace paper artifacts, but not always. If the client stakeholders you’re working with don’t have the authority to approve the work, then you need to provide them with things to show and tell internally. Sometimes this means paper.

Geoffrey Graham 16 Mar 06

There are striking similarities between the concepts discussed here (the development of web-based environments) and the ongoing discussions of the development of our built (i.e. land, houses, etc) environment. So much so that I am stuck everyday with an Ah-ha! moment that shines a glaring spotlight somewhere. This is one.

I encourage you to check out Jane Jacobs’ “Death and Life of Great American Cities” to get her prescient (1950s) comparison of evolved (vibrant) communities with authoritarianly planned (dying) communities. More recently (late 90s), she applied the same kind of analysis to all types of organisms (whether small groups, living eco-systems or economies) in “The Nature of Economies”.

Her finding: Rigid Plan = Crap; Responsive Design = Awesome.

There are other striking similarities in the web/real estate worlds , as well. Pretty neat.

Christian Pascault 17 Mar 06

If the common law is the superior way so why the US Democrats so afraid of any new Supreme Court judge chosen by GW Bush ?
Writting specification should an on-going process and finishes when the software is delivered.
Other groups (e.g. software testers, Doc) are basing their own specification/materials on the specification so, at one point, it must be written and be the single “truth”.

al 19 Mar 06

I can see how a functional spec may seem superfluous if all your products are web-based apps. It’s so easy to iterate small and large changes alike based on near constant feedback from users. But try shipping shrinkwrapped compiled binaries..anything that can’t be changed on a webserver…without the discipiline that a quality spec process brings to the production lifecycle.

Specs…when used correctly…are not about making people “feel involved.” They’re about actually involving people and, hopefully, making all of your mistakes upfront in the early phase instead of later when a group of programmers are already well down the road. I think we would be hard pressed to find an example of a standout successful software product (sales and user satisfaction) that didn’t begin life as a successful spec as well.


-al

Juha 19 Mar 06

Naturally it is easier to iterate with web-based applications.

On ‘normal’ software the UI / feature iteration needs just to be done during or before actual programming. You can do surprisingly much with just pen and paper! (But it feels like ‘cheating’, it is too easy)

Lawrence Krubner 19 Mar 06

Ted Goranson got a grant from DARPA to do research on agility and one of his conclusions was that creativity had an easier time flourishing in nations that were run by case law. I’ve no idea if that conclusion is in the book I’m linking to, as I only read it in rough draft form. If you can get, the 6 page pamphlet will tell you everything you need to know.

Goranson points out that the only countries in the world with thriving, non-subisidized movie industries run on case law (India and America especially).

He asks how a few small town in Massachucetts were able to gain 90% market share for whaling, when most of the whales were in the Pacific. He points to things like case-law, which allows for light weight contracts built on top of previous precedent. He also points to trust, something that militantly trustworthy groups like the Quakers had in aces.

Lawrence Krubner 19 Mar 06

Common law gives judges no ‘creativity’ or freedom to acto on intuition - they *must* look at prior cases and then decide what key aspects of *those cases* are at issue.

What does previous law say about gay marriage circa 1998? Reproductive cloning circa 2001? Making a personal copy of a movie on a VCR circa 1981?

Case law is more flexible than code law. On this point, nearly all researchers on agility have agreed. Innovation will have an easier time of it in nations that practice case law, instead of code law. It’s because the judges have more freedom to invent precedent, when faced with truly new situations.

Lawrence Krubner 19 Mar 06

If you work in the real world, write it down so the dimwits don’t fuck it up.

Real World = really big companies

Small companies = not serious, not adult, the products they develop are just toys, to be laughed at.

Is that fair?

I think Jason’s point is that is that if you give people both responsibility and power, you can unleash a lot of creativity.


Every big company has a few of these people too, but they are outnumbered by tens, hundreds, or thousands of others with titles that preclude “the gurus” from working across disciplines.

That doens’t sound like a good way to make money. Maybe these companies should try a little harder to make some money.

daan 18 May 06

Love the concept.

Unfortunately…

Once you move into the realm of financials or any other industry with governing laws and large amounts of money flowing through your application one has to add the documentation, functional spec. documentation. People want check cross-check and check again.

If one can add this idea as an extra step for your bigger clients the impact would be huge in a positive way.

Post a comment

(Basic HTML is allowed)

NOTE: We'd rather not moderate, but off-topic, blatantly inflammatory, or otherwise inappropriate or vapid comments may be removed. Repeat offenders will be banned from commenting. Let's add value. Thank you.