The Design of Software (CLOSED)

A public forum for discussing the design of software, from the user interface to the code architecture. Now closed.

The "Design of Software" discussion group has been merged with the main Joel on Software discussion group.

The archives will remain online indefinitely.

Developers Designing

The place I work has had no real design work for each piece of a project.  The graphics designers design what something should look like, write functional specs which add little, and then the thing goes straight to code.

Much of our work is a mess.

Seeing this, it has been decided that a design document shall be written before code is written.


But the coders are doing the design.  Will making them write down their design make them design their solution any better than them doing it in their heads as currently?
Wednesday, November 30, 2005
In general, thinking about something before doing it is a good thing.
Sassy Send private email
Wednesday, November 30, 2005
I certainly became better at software development once I started writing design documents.

They don't even have to be particularly detailed, but it really does help to plan up front.  You can catch some errors that otherwise you wouldn't have caught until much too late.

My problem now is that my manager simply doesn't read the documents.  He even flat out admitted this to me.  Of course, I still get blamed when things are implemented according to spec but differently from how he imagined them.
Chris in Edmonton Send private email
Wednesday, November 30, 2005
This is one of those cases where the phrase "design document" means different things to different people.

In your specific case, because you're working with visually oriented people - the best design documents are a combination of flow charts and user interface mockups.  What I especially would recommend is finding some nice big flat surface (such as a conference room table or a blank wall) and give each person a stack of post-it notes and a pen.  Invite the designers to simply jot down an idea or a feature and stick it to the wall.

Encourage them to focus on atomic statements, for example "big picture of stamp sends mail", "mailbox flag goes up when new message arrives" and so on.

Because these are post-its, you will be able to logically arrange all of these ideas (just move the notes around) and see where the gaps are - for example, how do you indicate when there's mail ready to be sent?

A programmer - NOT a graphic designer - will be able to look at all these and construct a rudimentary flowchart, i.e., when people draft and send letters, they will need to click this, type here, click that, and so on.

Once the flowchart is done, you have a good idea of what the application needs to be able to do, when, and how.  Your programmers will then find it much easier to write clean, manageable code.
Anonymous Coward
Wednesday, November 30, 2005
I'm with Sassy on this one. More times than I can count, I have been stuck. Finally I turn away from the keyboard, write some notes and the "impossible" task is done in a few minutes.

So making people come up with designs will provide benefits even if nobody, including the codes, ever look at the design docs again.
dot for this one
Wednesday, November 30, 2005
> In general, thinking about something before doing it is a good thing

Only if your are capable of comming up with a good design, which seemed to be the implication of the post.
son of parnas
Wednesday, November 30, 2005
I'm the product manager at my company and I do the designs as wireframes in Visio. It's *just* enough for the developers to work from without stifling their creativity and avoids burying them with long, descriptive design documents. Window behaviors and user interactions are documented with call-outs; there's a section describing the window's purpose and who would use it; and another section for any special notes. It all fits on one landscape 8.5x11" page (i.e., one screen per page, that is).

If the devs are swamped, I turn the wireframes into an HTML prototype, with the stylesheets and javascripts I need to get the user experience I really want. And we usually hire a graphics designer to polish the whole thing up so it's a sharp looking piece of software.

From that point on, I tend to participate in development closely. Sometimes I simply review each build and make sure it performs as per the design; other times, when I have to, I get my fingers dirty, digging around in their code, making sure that the UI looks and does what the user expects.

All in all, it seems to work fairly well. But then, Product Management in my company reports up through Engineering, rather than Marketing, so I can participate much more directly in product development cycles.
the pragmatic product manager Send private email
Wednesday, November 30, 2005
> But then, Product Management in my company reports
> up through Engineering, rather than Marketing, so
> I can participate much more directly in product
> development cycles.

Isn't it nuts that organization structure changes how you can interact with people?
son of parnas
Thursday, December 01, 2005
I think this is not a good idea. Coders should just implement what was written by someone else. Coders are not good designers because they always think about technical aspects of the application, usualy start with tech issues too early and because of that their design is not user-oriented. You need a person that will think only about user needs and write down all user inteface, site map, functional spec and whatever. Soft. Architect or (experienced) coders should then write tech specification/design, class diagrams, sequences etc.

Zvonko Send private email
Thursday, December 01, 2005
"... making sure that the UI looks and does what the user expects. "

How do you know what that is? Or do you make sure the UI looks does what you think the user expects?

Do you have a user experience group at your company?
Another Joe
Sunday, December 04, 2005
In the course of my job, I have just been tasked with answering the pithy question 'what is (software) design?'. I would appreciate feedback!

It seems to me there are multiple levels or types of design. Design as carried out by user interface and interaction designers; design as carried out by solution designers; design as carried out by technical architects and design as carried out by developers.

I cannot see how any complex solution can be produced without careful understanding of what the problem is you are trying to solve (analysis), what the solution you intend to deliver is from the user's point of view (logical design, including UI), and how you intend to implement that solution (physical design, i.e. class design, code design etc.). All of this sits within/on top of the design of the product's technical architecture.

The more complex the product structure gets, the more important it is to document the design and proposed changes to it. This is especially important in package development, where multiple modules with complex features may exist, and these will continue to be developed and enhanced over many years. Changes need to be discussed and shared, since one person may not be aware of the implications of their proposals on some other part of the code or product. I personally believe, however, that a lot of the design - and especially the low level design - can be done through peer white boarding sessions, reaching agreement on the approach, and a quick email to document the agreement, without having to disappear under a pile of paper.
Sian Cooper Send private email
Monday, December 05, 2005
Because the UI is only a fraction of a working system, the UI developer should not be the only one in charge of writing a design document.  In fact, the UI developer should be writing the "User Guide", as opposed to a "design document", in addition to "Developers Guide / Cookbook".  These are 2 separate documents with different audiences.

That said, if a "design document" is required by anyone that someone better have a use for it.  The audience of a document determines the use of the document: user To user's guide, developer to cookbook, manager to ?, team lead to UML... Cross-functional guides, interfaces between layers, components or systems, should contain how-to information for the client side and are thus user's guides for that client. 
If you are able to identify the audience, you are able to tailor the document information to that level of expertise or use.

"Isn't it nuts that organization structure changes how you can interact with people?" son of parnas

This is the exact statment that a audience-focused "design document" will solve.  Being able to consider your audience no matter what you are writing (code, tests, user manuals...) will not only improve the readability of the document but will give the author a chance to really reflect on the chosen implementation and how it is viewed by others.  The less static, jargon, or noise a reader is expected to interpret the more useful the document is to that reader.

As far as writing a design document before the code is written - only if someone has a REAL need for that document and is aware it will be out of date the minute the first line of code is written.
A Non Anon
Monday, December 05, 2005

This topic is archived. No further replies will be accepted.

Other recent topics Other recent topics
Powered by FogBugz