no functional spec... gasp!

michelle.dsouza at michelle.dsouza at
Fri Nov 30 17:20:33 UTC 2007

Well said! I would add that doing 'hardcore agile' is next to  
impossible in a distributed environment. There's a lot to be said for  
being able to drag a designer over to my screen to show them my  
interpretation of past conversations. If we are co-located I can take  
advantage of this regularly enough that we might not need diagrams and  
documents other then scratches on the nearest white-board. Not having  
that ability with distributed resources means we must use other forms  
of communication. An added bonus of these diagrams and documents in an  
open source community is the ability to communicate the ongoing  
conversation with the whole community.


Quoting Yuji Shinozaki <ys2n at>:

> 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".
> yuji
> ----
> [1] e.g. Agile Software Development
> ASIN/0201699699
> [2], esp.
> index.php/ASD_book_extracts
> 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
> _______________________________________________
> fluid-work mailing list
> fluid-work at

More information about the fluid-work mailing list