no functional spec... gasp!

Fri Nov 30 15:31:31 UTC 2007

Right on...working documents that grease the communication between
functional folks, designers and developers.

I sense that there is resistance to even THIS level of technical modeling in
the community. I mentioned that it may be a good idea to write some
technical design docs at the last Ucamp. My sense was that the attendees
weren't that keen on the idea. Some had done some UML modeling before and it
must have left a bad taste in their mouth.

I am NOT a developer. If I couldn't model some ideas with developers, I
would have a really hard time making sure that we were speaking the same
language. Like Yuji infers, I can use models to facilitate discussions with
functional experts about how a system currently works just as easily as I
can use it to discuss new development with programmers.

Sean

On 11/30/07 9:39 AM, "Yuji Shinozaki" <ys2n at virginia.edu> wrote:

> 
> 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 http://www.amazon.com/exec/obidos/
> ASIN/0201699699
> [2] http://alistair.cockburn.us, esp. http://alistair.cockburn.us/
> 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 stanford.edu> wrote:
>> 
>>> Here's an interesting article I found when I googled on "annotate
>>> html
>>> mockups":
>>> http://www.37signals.com/svn/archives2/
>>> the_interface_as_a_spec_including_stori
>>> es_inline.php
>>> 
>>> but it led me to this:
>>> http://www.37signals.com/svn/archives/001050.php
>>> 
>>> no functional spec... gasp!
>>> 
>>> Actually, 37signals whole philosophy is pretty much a vector on
>>> traditional software development:
>>> http://gettingreal.37signals.com/index.php
>>> 
>>> Hmm, why do I like this?
>>> -mARC
>>> 
>>> ----------------------
>>> This automatic notification message was sent by Sakai Collab
>>> (https://collab.sakaiproject.org/portal) 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
>> (https://collab.sakaiproject.org/portal) 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 virginia.edu
> 
> 