no functional spec... gasp!

Yuji Shinozaki ys2n at
Fri Nov 30 14:39:22 UTC 2007

To me, the important idea here is that diagrams, documents and  
"specifications" are part of a conversation and none of should be  
considered the "final word".  I think that is what they really meant  
by "No Functional Specifications".

Borrowing greatly from Alistair Cockburn's books [1][2]: work  
documents are "artifacts" whose purpose is to get you to the next  
step and anything more is wasted effort.  The goal is sufficiency,  
not "completeness" or even accuracy.  They should just be "landmarks"  
and reminders of past conversations amongst stakeholders and  
developers.  Problems arise when people (developers and "customers")  
view functional specs as contracts that you hold another party to  
("hey, you said right here that the user should be lead through the  
process in sequence, you didn't say anything about being able to use  
the back button.").  You have to assume that communication between  
parties will be imperfect, and that is why iterative development,  
mockups, frequent deliveries, frequent conversations is so important.

The place where Agile philosophy tends to fall down is with  
documentation, or in more general terms, communication with people  
who weren't part of the original or ongoing conversation.  And I mean  
developer documentation (user documentation is another ball of wax  
with other issues).  Hardcore agile followers would say that the code  
should be the developer documentation, if your code can't read like  
documentation then you aren't coding in an agile fashion.  That can  
work at the code level, but as the software gets more complex and the  
interactions become more numerous, it starts getting impossible to  
read enough "code" to get the big picture.  So that's when developers  
look to the specifications to be complete and accurate: "the final  
word".  So maybe one should apply agile development methodology to  
the specifications themselves.  The code and the specifications  
change together...  The specification is no longer the "final word",  
just the "current word".


[1] e.g. Agile Software Development 
[2], esp. 

On Nov 30, 2007, at 5:56 AM, Sean Keesler wrote:

> Being a somewhat visual thinker, I can appreciate the idea of using  
> a UI
> design as a tool for helping communicate the functional spec to  
> developers.
> However, I think that it makes sense to use other modeling  
> techniques in a
> similar way to keep the conversation going between developers and  
> designers.
> A state diagram, decision table and/or data models are useful  
> techniques
> that can help to bridge the gap between concept and code. I can  
> often say a
> lot more with a quick diagram than I can with text and I have had  
> some great
> conversations with our developers with "traditional" modeling tools.
> I wouldn't advocate for creating extensive design documentation as a
> required deliverable before moving into coding, but when it works as a
> communication tool between willing parties, it sure helps.
> ------------------------------
> Sean Keesler
> The Living SchoolBook
> 030 Huntington Hall
> Syracuse University
> 315-443-4768
> On 11/30/07 3:04 AM, "Marc Brierley" <brierley at> wrote:
>> Here's an interesting article I found when I googled on "annotate  
>> html
>> mockups":
>> the_interface_as_a_spec_including_stori
>> es_inline.php
>> but it led me to this:
>> no functional spec... gasp!
>> Actually, 37signals whole philosophy is pretty much a vector on
>> traditional software development:
>> Hmm, why do I like this?
>> -mARC
>> ----------------------
>> This automatic notification message was sent by Sakai Collab
>> ( from the DG: User  
>> Interaction site.
>> You can modify how you receive notifications at My Workspace >  
>> Preferences.
> ----------------------
> This automatic notification message was sent by Sakai Collab  
> ( from the DG: User  
> Interaction site.
> You can modify how you receive notifications at My Workspace >  
> Preferences.

Yuji Shinozaki
Sr. Technical Lead/Project Manager
University of Virginia
Advanced Technologies Group
ys2n at

More information about the fluid-work mailing list