Design Deliverables and Developers

4 Mar 2008 - 3:15pm
6 years ago
27 replies
1459 reads
seele@obso1337.org
2005

One of the things I am interested as a designer is how we can work better with
developers. If you are lucky enough to work as part of an in-house team you
probably (hopefully) have a stronger relationship with developers than those
of use who only come in as consultants. Often as a consultant, the only
contact we have with the development team might be through the project
manager or technical lead. So we must rely on our design documents to
deliver our message.

Although we would all like our deliverables to be developer-friendly, they
don't always turn out that way. Many of the guidelines I've read for
creating client deliverables focus on impressing the client and not
necessarily getting work done. Sure, they also try to present the
information in a way that readers can understand them, but project managers
are a much different audience than developers who are actually doing the
work.

Does anyone know of studies or other research that explicitly looks at how
developers are using design deliverables in practice? Particularly
integrating things such as wireframes in to functional specifications. Or
even if developers "get" the wireframes and mockups we give them. I've found
that developers prefer annotated slides or a big numbered list of issues to
having to read anything big, but those types of things don't look as nice as
a fully written final report for the project manager.

Thoughts?

~ Celeste

--
Celeste 'seele' Paul
www.obso1337.org

Comments

4 Mar 2008 - 3:24pm
Rob Nero
2005

Though I do not have any research to backup your question, I do have a lot
of experience with handing off my designs/code to developers.

Rule #1: Be as specific as possible! :)

Our team typically goes through many iterations of design with the business
clients and project manager before handing anything to developers. With
this audience, we are presenting "glossy" mockups of the application along
with any necessary large-print diagrams. We are doing everything possible
to sell the design to the clients.

At the point of handing off to developers, we repackage the designs into
something more relevent to the developers. We call this converted document
a User Interface Specification Document. This document has a screenshot of
the mockup with numbers next to all of the screen components (fields,
labels, images, widgets, etc). Later in the document we list the numbers
along with all the necessary data that a developer cares about: field
length, validation, onblur, onfocus, onload, size, height, width, etc...

In this way, we hand off a high-fidelity mockup with a detailed document
explaining how everything works on the screen.

Does that help?
Rob

On Tue, 4 Mar 2008 15:15:33 -0500, "Celeste 'seele' Paul"
<seele at obso1337.org> wrote:
>
> Does anyone know of studies or other research that explicitly looks at
how
> developers are using design deliverables in practice? Particularly
> integrating things such as wireframes in to functional specifications.
Or
> even if developers "get" the wireframes and mockups we give them. I've
> found
> that developers prefer annotated slides or a big numbered list of issues
> to
> having to read anything big, but those types of things don't look as nice
> as
> a fully written final report for the project manager.
>
> Thoughts?
>
> ~ Celeste

4 Mar 2008 - 3:46pm
jason zietz
2007

I view design deliverables in the same way as I view whatever it is that
I'm designing: I'm building something for *someone*, so in order to get
it right, I must consult with them and understand their needs. It's
more important to me that I deliver something that conveys functionality
and behavior effectively without creating too much noise, i.e., usable
documentation.

In my most recent project, I communicated with the developer as I worked
on the documentation, providing him with samples of different options
(in the context of the project) so he could choose which type of
documentation best suited him.

Additionally, I'd recommend encouraging communication during the
development process when possible as things invariably arise that
weren't covered in the documentation.

> Does anyone know of studies or other research that explicitly looks at how
> developers are using design deliverables in practice? Particularly
> integrating things such as wireframes in to functional specifications. Or
> even if developers "get" the wireframes and mockups we give them. I've found
> that developers prefer annotated slides or a big numbered list of issues to
> having to read anything big, but those types of things don't look as nice as
> a fully written final report for the project manager.
>

4 Mar 2008 - 4:02pm
Ari
2006

This is something I deal with nearly every day - especially as we have 2
week dev cycles between product releases.

Everyone who has replied to the thread already has provided sage advice.

Let's put it this way...

most developers never get more than a few bullet points for specs or as
inputs while many others still work in environments of "oral history" where
deliverables are verbally explained but never written!

So, when a developer gets design docs and/or functional specs - even
imperfect ones, they are often happy.

The more you involve them in the process and the better you are in
communicating with developers as part of your deliverables, the smoother the
experience will be but to actually have something written that illustrates
what the desired output should be and explains what happens if 'user X
clicks on a button' and man, you'll be ahead of the game.

On 3/4/08, Celeste 'seele' Paul <seele at obso1337.org> wrote:
>
>
> One of the things I am interested as a designer is how we can work better
> with
> developers. If you are lucky enough to work as part of an in-house team
> you
> probably (hopefully) have a stronger relationship with developers than
> those
> of use who only come in as consultants. Often as a consultant, the only
> contact we have with the development team might be through the project
> manager or technical lead. So we must rely on our design documents to
> deliver our message.
>
> Although we would all like our deliverables to be developer-friendly, they
> don't always turn out that way. Many of the guidelines I've read for
> creating client deliverables focus on impressing the client and not
> necessarily getting work done. Sure, they also try to present the
> information in a way that readers can understand them, but project
> managers
> are a much different audience than developers who are actually doing the
> work.
>
> Does anyone know of studies or other research that explicitly looks at how
> developers are using design deliverables in practice? Particularly
> integrating things such as wireframes in to functional specifications. Or
> even if developers "get" the wireframes and mockups we give them. I've
> found
> that developers prefer annotated slides or a big numbered list of issues
> to
> having to read anything big, but those types of things don't look as nice
> as
> a fully written final report for the project manager.
>
> Thoughts?
>
> ~ Celeste
>
> --
>
> Celeste 'seele' Paul
> www.obso1337.org
> ________________________________________________________________
> Welcome to the Interaction Design Association (IxDA)!
> To post to this list ....... discuss at ixda.org
> Unsubscribe ................ http://www.ixda.org/unsubscribe
> List Guidelines ............ http://www.ixda.org/guidelines
> List Help .................. http://www.ixda.org/help
>

--
--------------------------------------------------
www.flyingyogi.com
--------------------------------------------------

4 Mar 2008 - 4:23pm
seele@obso1337.org
2005

On Tuesday 04 March 2008 15:24:03 Rob Nero wrote:
> In this way, we hand off a high-fidelity mockup with a detailed document
> explaining how everything works on the screen.

Do you create a separate client deliverable or give the same thing to you
project contact (or are you part of an integrated or in-house team so "plop"
factor doesn't matter as much).

On Tuesday 04 March 2008 15:46:14 Jason Zietz wrote:
> In my most recent project, I communicated with the developer as I worked
> on the documentation, providing him with samples of different options
> (in the context of the project) so he could choose which type of
> documentation best suited him.
>
> Additionally, I'd recommend encouraging communication during the
> development process when possible as things invariably arise that
> weren't covered in the documentation.

I always prefer to work closely with developers, but that doesn't always
happen. That is why I am so interested (and concerned) about deliverables.
A wireframe can be both a helpful and dangerous tool, depending on how much
you read (or don't read) in to it. Also, developers are used to different
kinds of documentation, so a written point-by-point specification might
resonate with them more than a picture. Who knows? (That is why I am asking
these questions).

On Tuesday 04 March 2008 16:02:55 Ari Feldman wrote:
> most developers never get more than a few bullet points for specs or as
> inputs while many others still work in environments of "oral history" where
> deliverables are verbally explained but never written!
>
>
> So, when a developer gets design docs and/or functional specs - even
> imperfect ones, they are often happy.

I totally agree unless they are handed an 80 page report of 6 months of
research. And a cup of coffee. And some aspirin.

There are lots of things that "should" happen in a project -- clear product
goals and documentation, communicating with developers, writing perfect
reports, lots of extras to tape on the wall -- but they don't always happen.
Maybe it is just the capacity I work in (aka miracle worker) that nothing
goes as planned. I usually get called in to the middle of a project which is
in serious trouble and get caught between backfilling necessary user research
and "fixing it now". It is really about making the best of what you got and
hoping your message gets across. And being thankful the client is thinking
about these things at all.

Is there a SIG for Guerrilla Design?

--
Celeste 'seele' Paul
www.obso1337.org

4 Mar 2008 - 4:33pm
Mark Schraad
2006

We have moved away from comprehensive PRD, DRD and TRD's. They are slow,
painful. They also tend to reduce dialog. As a designer, I really like the
interaction and realtime dialog with the dev group. They are included up
front so that the communication during the dev cycle is pretty open. This
helps to make the dev review a little less harsh.
As for docs, we deliver mocks - typically as pdf with layered annotation.
Often times we script the interactions with flash or html, but that is
fairly rare. We also have a wiki for nearly every project and nearly daily
team updates.

Mark

On Tue, Mar 4, 2008 at 3:15 PM, Celeste 'seele' Paul <seele at obso1337.org>
wrote:

>
> One of the things I am interested as a designer is how we can work better
> with
> developers. If you are lucky enough to work as part of an in-house team
> you
> probably (hopefully) have a stronger relationship with developers than
> those
> of use who only come in as consultants. Often as a consultant, the only
> contact we have with the development team might be through the project
> manager or technical lead. So we must rely on our design documents to
> deliver our message.
>
> Although we would all like our deliverables to be developer-friendly, they
> don't always turn out that way. Many of the guidelines I've read for
> creating client deliverables focus on impressing the client and not
> necessarily getting work done. Sure, they also try to present the
> information in a way that readers can understand them, but project
> managers
> are a much different audience than developers who are actually doing the
> work.
>
> Does anyone know of studies or other research that explicitly looks at how
> developers are using design deliverables in practice? Particularly
> integrating things such as wireframes in to functional specifications. Or
> even if developers "get" the wireframes and mockups we give them. I've
> found
> that developers prefer annotated slides or a big numbered list of issues
> to
> having to read anything big, but those types of things don't look as nice
> as
> a fully written final report for the project manager.
>
> Thoughts?
>
> ~ Celeste
>
> --
> Celeste 'seele' Paul
> www.obso1337.org
> ________________________________________________________________
> Welcome to the Interaction Design Association (IxDA)!
> To post to this list ....... discuss at ixda.org
> Unsubscribe ................ http://www.ixda.org/unsubscribe
> List Guidelines ............ http://www.ixda.org/guidelines
> List Help .................. http://www.ixda.org/help
>

4 Mar 2008 - 4:38pm
Ari
2006

>
>
>
> On Tuesday 04 March 2008 16:02:55 Ari Feldman wrote:
> > most developers never get more than a few bullet points for specs or as
> > inputs while many others still work in environments of "oral history"
> where
> > deliverables are verbally explained but never written!
> >
> >
> > So, when a developer gets design docs and/or functional specs - even
> > imperfect ones, they are often happy.
>
>
> I totally agree unless they are handed an 80 page report of 6 months of
> research. And a cup of coffee. And some aspirin.

Size does matter but it should be gauged according to the complexity and
type of project. I've generated some specs that are 500 pages and many are
easily dozens.

With the correct process in place, you can determine the right size to
convey your deliverables in as well as the fidelity. It must be appropriate
to the task/project.

If size becomes an issue, you can always break it up into modules. This is
how programs are written and the same logic can be applied to deliverables
as often, multiple developers may share parts of a given development
project.

Some programmers will follow deliverables to the letter (both good and bad)
while others will question what you've delivered either due to the lack of
clarity or an unforeseen case or limitation.

Your deliverables need not be cannon (unless you're Boeing) or have the
luxury of time. Rather, deliverables must deliver the intent, outline the
desired results and be flexible enough to be thorough without being
overwhelming to peruse.

Good communication between team members is a must regardless of your
approach.

> There are lots of things that "should" happen in a project -- clear
> product
> goals and documentation, communicating with developers, writing perfect
> reports, lots of extras to tape on the wall -- but they don't always
> happen.
> Maybe it is just the capacity I work in (aka miracle worker) that nothing
> goes as planned. I usually get called in to the middle of a project which
> is
> in serious trouble and get caught between backfilling necessary user
> research
> and "fixing it now". It is really about making the best of what you got
> and
> hoping your message gets across. And being thankful the client is
> thinking
> about these things at all.

Welcome to my world. If I followed every formal step, we'd never release
anything. With practice (and success as well as failures) you live, you
learn and figure out how to make the best use of your time and resources to
deliver the best documentation and deliverables you can while meeting your
desired goals.

Like many things in these disciplines, this is part art and part science
with a little voodoo in-between.

Is there a SIG for Guerrilla Design?
>
>
> --
> Celeste 'seele' Paul
> www.obso1337.org
> ________________________________________________________________
>
> Welcome to the Interaction Design Association (IxDA)!
> To post to this list ....... discuss at ixda.org
> Unsubscribe ................ http://www.ixda.org/unsubscribe
> List Guidelines ............ http://www.ixda.org/guidelines
> List Help .................. http://www.ixda.org/help
>

--
--------------------------------------------------
www.flyingyogi.com
--------------------------------------------------

4 Mar 2008 - 4:52pm
Rob Nero
2005

I am apart of an integrated in-house team. Everyone involved with a given
project is employed by the same company. So that does give me an advantage
that I can easily go over to any developer's cube and chat with him/her
about my design or what they need.

We will create separate deliverables depending on the recipient. The
business clients and project manager will receive just the screen designs
and high-level diagrams of flow and interaction. The developers would
receive the ultra-detailed spec documents of each screen in the
application. We typically create a separate spec doc for each screen in a
web app.

Like you say… things usually never go as planned. Even though I can
create the frontend html code and hand that off with a full spec doc for
each screen… the final app typically does not look exactly how I had
envisioned it. Things get lost in translation. :)

On Tue, 4 Mar 2008 16:23:56 -0500, "Celeste 'seele' Paul"
<seele at obso1337.org> wrote:
> On Tuesday 04 March 2008 15:24:03 Rob Nero wrote:
>> In this way, we hand off a high-fidelity mockup with a detailed document
>> explaining how everything works on the screen.
>
> Do you create a separate client deliverable or give the same thing to you
> project contact (or are you part of an integrated or in-house team so
> "plop"
> factor doesn't matter as much).
>

4 Mar 2008 - 5:11pm
Scott Berkun
2008

From: "Celeste 'seele' Paul" <seele at obso1337.org>

> Does anyone know of studies or other research that explicitly looks at how
> developers are using design deliverables in practice? Particularly
> integrating things such as wireframes in to functional specifications. Or
> even if developers "get" the wireframes and mockups we give them. I've
found
> that developers prefer annotated slides or a big numbered list of issues
to
> having to read anything big, but those types of things don't look as nice
as
> a fully written final report for the project manager.

Some opinions/questions:

1. Why only have one deliverable? If you're convinced developers want
something diferent from what the client liason wants, design your
deliverables that way. Have a section in your spec marked "For developers"
or create two seperate documents for the two different purposes.

2. By far the most common thing I've seen developers do with design
documents, if anything at all, is hold up screenshots in the printed doc
next to the screen and work to make 'em match. In fact I've had many
programmers tell me they skip through the spec, and mostly focus on the
screens. Like Rob suggests, make sure any screenshots you have are labeled
with font names, Hex codes for colors, font sizes, pixel widths, etc. to
make it as easy as possible to get those details right. The easier you make
those precise details to understand, the higher the odds the developer will
actually do them.

2+. Do an informal usability study on your deliverables - Seriously, have
you ever watched someone actually use what you make? Or gotten feedback from
them on how it could have been more useful? Or gone back later to see how
much of what was in your deliverable actually made it into the final
release? If you treat your delvierables like a user experience, you can
apply tons of basic UX techniques to your specs, prototypes, wireframes,
reports, etc.

3. Ask, early, to have at least one meeting with an actual developer, even
if it's with the project liason from your client also there. That will give
you a chance to ask the developer directly how they like to work, what
they're most concerned about and what the best way is to help them with your
talents. Even a 5 minute meeting will make it more comfortable to follow up
later and ask questions. Design documents are worthless without a
relationship behind them - there are always assumptions and interpretations
and without a relationship there is no effective way to resolve them.
Initiate contact, ask for feedback, and follow up later to ask if there are
questions or problems.

4. Every consultancy and client are different - so if you're not sure how
the stuff you make is being used on any project, go find out. It's entirely
reasonable for you to ask your clients about this, since the more you know
about how your stuff is used (even if it's being mostly ignored) the higher
the odds you'll make something more useful next time.

-Scott

Scott Berkun
www.scottberkun.com

4 Mar 2008 - 5:42pm
seele@obso1337.org
2005

On Tuesday 04 March 2008 17:11:23 Scott Berkun wrote:
> 1. Why only have one deliverable? If you're convinced developers want
> something diferent from what the client liason wants, design your
> deliverables that way. Have a section in your spec marked "For developers"
> or create two seperate documents for the two different purposes.

Personally I create two deliverables, the big fat report for project manager
to put on his shelf and then something more useful for developers to refer to
that corresponds with the report and is easier to flip through and print.

Basically I asked these questions because I was curious to see how other
people are handling this problem.

> 2+. Do an informal usability study on your deliverables - Seriously, have
> you ever watched someone actually use what you make? Or gotten feedback
> from them on how it could have been more useful? Or gone back later to see
> how much of what was in your deliverable actually made it into the final
> release? If you treat your delvierables like a user experience, you can
> apply tons of basic UX techniques to your specs, prototypes, wireframes,
> reports, etc.

^ This is something I'm planning on doing. I brought up this discussion to
fill in anything I might not have thought of.

--
Celeste 'seele' Paul
www.obso1337.org

4 Mar 2008 - 5:59pm
Joe Sokohl
2004

Also, I highly, highly recommend Dan Brown's book "Designing
Documentation." Pretty much covers most deliverables for a project.

That said, I always try to do some interviews with developers to find
out what speaks to them.

joe

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Posted from the new ixda.org
http://www.ixda.org/discuss?post=26800

4 Mar 2008 - 11:37pm
Michael Micheletti
2006

Hi Celeste,

I work with an in-house dev team and find they are truly grateful when I
document a handful of details in addition to the general broad brush-strokes
of wireframes, layouts, etc:

- Error and status messages, especially when a consistent word order format
is used.
- Dimensions of images and graphical assets.
- State charts of complex controls (you click this here and that lights up
there, except when this other deelie is held down).

What these have in common is they're all head-scratchers that take the poor
developer out of flow and make them puzzle over what really ought to happen
in a situation. They have to stop being a developer and start being a
designer. I know (from trying to switch back the other way sometimes) that
this is a difficult leap to make quickly.

Some simple web forms get total documentation of a quickie Visio wireframe
drawing and a page of accompanying text and that's it, everybody's happy,
but more complex rich client components may end up with many pages of
detailed docs plus some sort of prototype to play with.

Oh one other thing I've noticed is that product managers and marketing folks
love to extract high-level feature lists from development requirements docs
and use them for their own nefarious purposes. So I've been putting this
information in tables lately in an intro section to make it easier for them.

Michael Micheletti

5 Mar 2008 - 6:52am
Stew Dean
2007

On 04/03/2008, Celeste 'seele' Paul <seele at obso1337.org> wrote:

> Does anyone know of studies or other research that explicitly looks at how
> developers are using design deliverables in practice? Particularly
> integrating things such as wireframes in to functional specifications. Or
> even if developers "get" the wireframes and mockups we give them. I've found
> that developers prefer annotated slides or a big numbered list of issues to
> having to read anything big, but those types of things don't look as nice as
> a fully written final report for the project manager.
>
> Thoughts?
>
> ~ Celeste

Very qucikly...

Often there is a cultural clash between the 'traditional' developer
process and the new processes that have grown involving wireframes,
flow diagrams etc.

The key is the correct definition of the functional specification in
such a way as it's usable and understandable to developers. In essence
they are the audience you need to make happy - I have often created
overviews for broader audiences and prototypes are increasingly used.

The wireframes make up most of the functional specification. Tools
like Axure output a word document that is essentialy a retelling of
the wireframes which some developers are used to working with. So
sometimes detailed wireframes with all the error states are enough and
are understandable, sometimes wirefreames with a word file and or
excel spreadsheet are needed. Other times a good set of diagrams and
wireframes are all that's needed. They become the functional spec.

The end aim is to present the information needed to ensure that what
is envisenged is built and that there are not gaps that the developers
fill in because it wasnt covered.

It's always best to try and work with the developers rather then doing
the design and throw it over the wall, it just means that the
wireframes are more realistic and some of the arbitary decisions we
all make can often be made in favour for more 'doable' options. It
increases the likelyhood of final delivery.

--
Stewart Dean

5 Mar 2008 - 3:52pm
Suba Periyasami
2008

On Wed, Mar 5, 2008 at 3:52 AM, Stew Dean <stewdean at gmail.com> wrote:

> On 04/03/2008, Celeste 'seele' Paul <seele at obso1337.org> wrote:
>
> > Does anyone know of studies or other research that explicitly looks at
> how
> > developers are using design deliverables in practice? Particularly
> > integrating things such as wireframes in to functional specifications.
> Or
> > even if developers "get" the wireframes and mockups we give them. I've
> found
> > that developers prefer annotated slides or a big numbered list of
> issues to
> > having to read anything big, but those types of things don't look as
> nice as
> > a fully written final report for the project manager.
> >
> > Thoughts?
> >
> > ~ Celeste
>

I found the book "Communicating Design <http://www.communicatingdesign.com/>"
to be useful.

In our company, during initial brainstorming meetings, we involve the
developers and discuss the design. They are also the product experts and
will usually have a lot of feedback to give us. Based on the discussions and
feedback, we develop screen designs and get an agreement on the design. We
then use the screen designs and create html mockups and include detailed
documentation that lists how the links will behave, what components are
disabled, what page will launch when a button is clicked, is it a action
button, how a show/hide button helps the user and so on.

Documenting the decisions we made is important so we can look back at the
end of the project and recollect where we made important decisions and why
the design looks and behave in a certain way.

We made it a practice to even document the original design and alternate
designs we came up with and why it was rejected by the product development
team. This helps us to recollect what tasks need to be tested or answer any
questions that executives/users have during or after the release.

Finally, before handing the document off to the developers, we review the
document with a teammate or with a member in the development team who we can
trust. This will help us to make sure if the design is explained clearly and
information is organized well. In our company, the QA uses this design spec
to test the product interface.

If there are multiple audiences for the document, organizing the content in
to different sections and indicating who should care about this section
(using visuals cues like different people icons for developers, project
managers and so) will help people to ignore stuff that is not relevant to
them.

8 Mar 2008 - 3:26pm
Gloria Petron
2007

I'm an in-house designer who sits on the same floor as the development team,
doing a lot of enterprise system work. It's good to find that groove that
works with your developers (for us, nothing gets results like a clickable
HTML/CSS prototype, accompanied by an MSWord doc with screenshots of the
different error screens...all meticulously dated so no one accidentally
designs to the wrong version), but be warned: sometimes you can get so
wrapped up in how you & the developers communicate that you forget your end
user. In the past, if an interface needed a fix, because I wanted to keep
confrontations to a minimum I would unconsciously design a solution that
stayed within the programmers' comfort zone. (This happened during a project
last year, and the end users spanked me for it.) Looking back I know now
there were times when - for a truly usable solution - I should have been
more of a hard-ass.

This isn't necessarily true for other settings, but for large-scale
enterprise apps, I would venture that the quality of the deliverables you
give to your developers is informed by the quality of the deliverables you
have with your end users. If all you've got are a couple hour's worth of
user interviews (which often turn into rant sessions and pie-in-the-sky wish
lists) and some Photoshop mockups, it won't matter how well you communicate
with the developers, you're not going to get the biggest bang for your buck.
I think every company has its own "thing" that works for them, discovered by
trial and error. But now that I've figured out how to communicate with my
development team, I'm more free to focus on creating research deliverables
that...(wait for it) feed into the deliverables that go to the development
team.

-G

10 Mar 2008 - 12:09pm
Angel Anderson
2010

I work in house, side-by-side with the developers so I have the luxury
of collaborating often and verbally walking them through my form &
behavior specs to answer questions that arise. We even get to have
regular, iterative comparative reviews between what's in the spec
and what they've been developing so that the final product is what I
envisioned. A recent acquisition however has meant that I'm now also
designing specs for a team in London and another team in India - talk
about things getting lost in translation!

Now I have to be more exact than ever but this is good for me - it
forces me to be even more clear and rigorous. At the end of the day
it all comes down to what Rob listed as Rule # 1: Be as specific as
possible!

I would also add rules 2 & 3:

# 2: A picture is worth a thousand words - make the pictures tell the
story as much as possible.

# 3: Be concise! Nobody wants to read a 500 page spec no matter how
pretty it is. ;-)

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Posted from the new ixda.org
http://www.ixda.org/discuss?post=26800

11 Mar 2008 - 5:02am
vlad
2008

Hi everyone.

Angel said: " # 3: Be concise! Nobody wants to read a 500 page spec no
matter how
pretty it is. ;-) "

Now I have to reply to this. To "be as specific as possible" means to give
as much detail as one would need to perfectly and thouroughly understand the
problem at hand. Isn't this rule in contradiction with your #3? :-P

I feel devs need to be explained. Assuming that the login system shouldn't
be explained, because it's ...well.. too common, is a bad step, imo.
Designers and developers often have different backgrounds, coming from
different cultures, things that influence their take on certain aspects of
the web. Therefore, "more is more", I think, when it comes to documents:
taking out all the assumptions and just documenting the project all the way
might save valuable time.

That being said, a picture not only tells more (#2), but it occupies less
space. So, the answer is probably in the middle somewhere.

10 Mar 2008 - 8:31pm
Wesley Hall
2007

I work for an in-house design team that collaborates with third
parties. As designers, we get paired up with internal producers
(assignments rotate), and then outsource to third-party developers.
The producer manages the primary relationship, and the designers
weigh in on key deliverables.

What we do:
1. High Concept Powerpoint for Marketing and Other Biz Partners
- Goal: Get Buy In
- they want the top level to make sure we're on strategy
- we include images to help them visualize the product
- we include bullet point lists of key feature sets
- we include preliminary user research data from qualitative testing

Once there's buy off....

2. Create Design Document Lite
- Goal: Solicit accurate & fair developer bids
- We include enough detail to communicate the scope of the project,
whatever it takes
- We don't go deep into design details, because there's usually a
time issue
- Meanwhile, we keep refining the concept and user testing

Select a winning bid, then...

3. Create Complete Design Document
- Goal: Enable a Great Kickoff Meeting & Create a Reference
- Include as much detail as appropriate to communicate the spec

But at this point it becomes a collaborative work and a conversation
with the developer. The process is organic and it varies by project.

Over-documentation is definitely a no-no to watch out for. You
don't want to make your docs so detailed that you spend all your
time updating them instead of communicating with your developer.

Regular conversation is key. You want to stay on the same page.

We used to document a lot more as a company, and would write docs
that spelled everything out to the letter. But what we found is that
the more we wrote, the less the developers read. You have to keep it
simple.

Pictures, labeled diagrams and prototypes definitely help.

If you use text, bullet point it. No one likes to read paragraphs.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Posted from the new ixda.org
http://www.ixda.org/discuss?post=26800

11 Mar 2008 - 1:27pm
stauciuc
2006

On Tue, Mar 11, 2008 at 12:02 PM, vlad <vlad.fratila at gmail.com> wrote:

> Hi everyone.
>
> Angel said: " # 3: Be concise! Nobody wants to read a 500 page spec no
> matter how
> pretty it is. ;-) "
>
> Now I have to reply to this. To "be as specific as possible" means to give
> as much detail as one would need to perfectly and thouroughly understand
> the
> problem at hand. Isn't this rule in contradiction with your #3? :-P
>
>
Not necessarily, I would say. You can give all the needed details in a
concise or a less concise way. Did you really need 500pages to give all the
*needed* details or would 50 have been enough? I guess it's about how
efficient your communication is, given you know what needs to be
communicated.

--
Sergiu Sebastian Tauciuc
http://www.sergiutauciuc.ro/en/

11 Mar 2008 - 1:44pm
Ari
2006

Length really depends on the audience and the application.

Once you've done a few release cycles with your dev team, you learn the
optimal size for your specs as well as the fidelity required for them.

This is particularly true when you are working on a product with existing
features, workflow and conventions, etc.

Being thorough is key but so is being as concise as possible - this
minimizes superfluous information and reduces the time required to generate
the documentation in the first place.

Of course, YMMV according to your needs, team and particular process.

On 3/11/08, Sebi Tauciuc <stauciuc at gmail.com> wrote:
>
> On Tue, Mar 11, 2008 at 12:02 PM, vlad <vlad.fratila at gmail.com> wrote:
>
> > Hi everyone.
> >
> > Angel said: " # 3: Be concise! Nobody wants to read a 500 page spec no
> > matter how
> > pretty it is. ;-) "
> >
> > Now I have to reply to this. To "be as specific as possible" means to
> give
> > as much detail as one would need to perfectly and thouroughly understand
> > the
> > problem at hand. Isn't this rule in contradiction with your #3? :-P
> >
> >
>
> Not necessarily, I would say. You can give all the needed details in a
> concise or a less concise way. Did you really need 500pages to give all
> the
> *needed* details or would 50 have been enough? I guess it's about how
> efficient your communication is, given you know what needs to be
> communicated.
>
>
> --
> Sergiu Sebastian Tauciuc
> http://www.sergiutauciuc.ro/en/
>
> ________________________________________________________________
> Welcome to the Interaction Design Association (IxDA)!
> To post to this list ....... discuss at ixda.org
> Unsubscribe ................ http://www.ixda.org/unsubscribe
> List Guidelines ............ http://www.ixda.org/guidelines
> List Help .................. http://www.ixda.org/help
>

--
--------------------------------------------------
www.flyingyogi.com
--------------------------------------------------

12 Mar 2008 - 10:50am
Michael B. Moore
2008

Hi - I've been lurking here, but this is too good a discussion to pass up.
One audience for documentation that hasn't been mentioned is the QA group.
As much as the developers, they need enough detail to develop test plans and
make sure the app works as designed.

I agree with the comments that mostly developers focus on the pictures, so
if there's a tricky bit I'll usually highlight it with some close-ups of
that portion of the screen. Usually the developers are on a tight deadline,
so an overly long document just isn't going to be read.

For one of my longer term clients, I've taken to providing static HTML pages
and accompanying CSS, with some JS libraries plugged in to show parts that
animate. The skill level among the developers when it comes to CSS is pretty
variable, so many of them appreciate not having to tackle the layout and
styling issues. It also means that the colors and fonts don't need to be in
the spec - they are available in the prototype. Obviously, the developers
don't use my JS code, and they replace the static items with Java calls, but
the process has been working well for everybody.

I'm curious though - for things that animate, appear and disappear, are
people detailing these behaviors in a document, and if so, how?

12 Mar 2008 - 12:03pm
stauciuc
2006

On Wed, Mar 12, 2008 at 5:50 PM, Michael Moore <mmoore at pureinfodesign.com>
wrote:

> Hi - I've been lurking here, but this is too good a discussion to pass up.
> One audience for documentation that hasn't been mentioned is the QA group.
> As much as the developers, they need enough detail to develop test plans
> and
> make sure the app works as designed.
>
>
Very good point!
And while you mentioned this, does that mean that there are QA persons out
there that have to fill in the blanks and do some design work when the
design spec isn't detailed or clear enough?

--
Sergiu Sebastian Tauciuc
http://www.sergiutauciuc.ro/en/

12 Mar 2008 - 12:13pm
dmitryn
2004

Yes, it does. As is the case with developers, throwing a design spec
full of holes over the wall to the QA team does not usually result in
good team morale or a well-designed product.

Dmitry

On Wed, Mar 12, 2008 at 10:03 AM, Sebi Tauciuc <stauciuc at gmail.com> wrote:
> Very good point!
> And while you mentioned this, does that mean that there are QA persons out
> there that have to fill in the blanks and do some design work when the
> design spec isn't detailed or clear enough?
>
>
> --
> Sergiu Sebastian Tauciuc
> http://www.sergiutauciuc.ro/en/
>
>
> ________________________________________________________________
> Welcome to the Interaction Design Association (IxDA)!
> To post to this list ....... discuss at ixda.org
> Unsubscribe ................ http://www.ixda.org/unsubscribe
> List Guidelines ............ http://www.ixda.org/guidelines
> List Help .................. http://www.ixda.org/help
>

12 Mar 2008 - 12:15pm
Scott McDaniel
2007

On Wed, Mar 12, 2008 at 1:03 PM, Sebi Tauciuc <stauciuc at gmail.com> wrote:
> Very good point!
> And while you mentioned this, does that mean that there are QA persons out
> there that have to fill in the blanks and do some design work when the
> design spec isn't detailed or clear enough?

Yes, definitely. Too often, it seems, because the same attention to
detail and specific knowledge of the design
come into play from different angles. Sometimes it's with the 'many
hats' philosophy, many times
because there's f-all enough people to do things separately.

Scott

--
'Life' plus 'significance' = magic. ~ Grant Morrison

12 Mar 2008 - 4:31pm
Wesley Hall
2007

Regarding QA:

I'd say yes, you want to be clear for QA. But finding the right
balance between "explicit" and "concise" is key.

A cautionary tale:
Once upon a time at my company we wrote air-tight docs. The docs were
so explicit they left *nothing* to the imagination, and QA straight
lifted them as test plans.

You'd think this would be a good thing. But it wasn't.

Our docs became very long and very detailed.
A single product might have 700 pages of documentation.

As the design morphed during production (as it always does based on
user test results, etc) it became impossible to keep the docs 100% up
to date. We tried hard to do it. Everybody was working crazy hours,
nights and weekends -- just to update the docs!

Then we hit the QA cycle. Our poor testers had to comb through 700
pages. Every time they hit a discrepancy between design and
documentation, bam they had to log a bug. Even if the design
essentially made sense.

Then you're looking at 1000s of bugs (as a designer or project
manager) and sorting them into "doc bugs" versus "real bugs".

Then there's the happy fun of going back and updating 700 pages of
docs. When really, you don't want to even DEAL with the docs --- you
want to spend your energy on building the best product.

So, with too much focus on documentation, everybody's productivity
is lowered and dev costs go through the roof.

So, we've changed policy. Now we make sure to be concise. We are as
detailed as possible wherever necessary. And we explain the GOAL of
the design.

Our Design Docs are radically shorter these days. It saves everyone
time and money. And so far, we're managing to keep clarity on the
designs just fine.

For the record, I should say I work for LeapFrog toys. So we're not
building web sites. We're building interactive books, games, toys,
etc. Still, we have similar documentation issues to anyone creating
digital products.

Perhaps it's not as much of an issue for web based products.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Posted from the new ixda.org
http://www.ixda.org/discuss?post=26800

12 Mar 2008 - 11:49pm
Michael B. Moore
2008

Good point on keeping the document up to date as development is ongoing.
This is something I struggle with doing consistently. You know the drill, a
developer comes up and asks about what the app should do in a particular
corner case, or can't implement something exactly as designed, and you talk
it over and make a decision and say to yourself, "I need to remember to put
that in the spec." but somehow it often drops to the bottom of the stack.

13 Mar 2008 - 3:24pm
Kevin Doyle
2007

Hi Celeste,

Are you familiar with Scrum or Agile project management? When
developers are working on a project within an Agile/Scrum project,
they are required to work with everyone working in the same room. Dev
teams are usually very small in Agile projects -- usually 2-4
developers, a UI/UX designer, a project manager (or Scrum Master) and
a representative of the project owners. I've very rarely worked on a
perfect Agile or Scrum project, but I've always requested that, no
matter what, I'm always working in the same room or space as the
developers. It creates a bond with all the developers and if anyone
has any questions, there's no silly email chain (passing of the
buck) for the answers.

Working in the same room with the developers also prevents the
typical project siloing -- where you work on the UI, then throw it to
the dev silo without looking back.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Posted from the new ixda.org
http://www.ixda.org/discuss?post=26800

13 Mar 2008 - 3:41pm
seele@obso1337.org
2005

On Thursday 13 March 2008 09:24:12 Kevin Doyle wrote:
> Hi Celeste,
>
> Are you familiar with Scrum or Agile project management? When
> developers are working on a project within an Agile/Scrum project,
> they are required to work with everyone working in the same room. Dev
> teams are usually very small in Agile projects -- usually 2-4
> developers, a UI/UX designer, a project manager (or Scrum Master) and
> a representative of the project owners. I've very rarely worked on a
> perfect Agile or Scrum project, but I've always requested that, no
> matter what, I'm always working in the same room or space as the
> developers. It creates a bond with all the developers and if anyone
> has any questions, there's no silly email chain (passing of the
> buck) for the answers.
>
> Working in the same room with the developers also prevents the
> typical project siloing -- where you work on the UI, then throw it to
> the dev silo without looking back.

Hi Kevin,

Yes, I am familiar with Agile but have only heard of Scrum. The Open Source
development cycle is very similar to these with very short development
periods of ongoing fix-release-fixing. The problem is that in Open Source,
contributors (developers, usability specialists, project managers, etc.) are
scattered all over the world, so we don't get the benefit of sitting in a
room and working together. Luckily some of the projects I work with have
commercial organizations who support design and development, and so a few
times a year we get together and bang out some of the tougher problems.

In the meantime, I have to rely on mailinst lists, blogs, IRC chat, and my
deliverables to get the message across. Most of the deliverables are never
printed so I have to consider that. Most of the time English is a second
language, and even though most of the developers I work with speak excellent
English (I sometimes suspect better than I do), I still have to be careful
about context and semantics. Also, issues must be written up in a way that
make it easy for bugs to be submitted because bug tracking systems are the
primary way many projects manage feature specifications and tasks.

It's interesting you mention creating a bond with developers, because that is
one of the most important things to do when trying to design in open source.
Code is a little different where anyone can compile it and see if it runs,
and a number of contributions are made psuedo-anonymously. However making
changes to a design requires a certain amount of trust to be built between
the designer and the developers. The designer isn't going to write the UI
code, and the developer isn't going to write UI code he doesn't believe in.
The developer isn't going to believe in the UI design unless he believes in
the designer.

~ Celeste

--
Celeste 'seele' Paul
www.obso1337.org

Syndicate content Get the feed