Fog Creek Software
Discussion Board




Why Not Use Diagrams and Models?

When engineers discuss an engineering problem, the first thing they do is go to the board and draw a picture of the situation.  "Okay guys, this is the cross section of concrete, here are the finite elements, the arrows are the heat transfer..."  Physicists?  Same thing.  They'll even draw pictures of things that you can't really draw pictures of: sub-atomic particles, higher-dimensions, etc.  Mathematicians?  Yep.  They diagram the most abstract things conceivable.  How about accountants?  I just saw a bunch of bean-counters with a huge flowchart on the grease board modeling some tax strategies.

Why do people do this?  The answer is plain as the nose on Barbara Steisand's face:  Because a picture is worth a thousand words.  Models allow us to abstract and grasp things much, much, much more easily than by just hearing someone speak.

What about software engineers?  I just sat through three long meetings where people were discussing what ID columns to add to database tables to accomplish some task - and there are more meetings to come.  If someone had drawn a stupid ER diagram, it would have taken fifteen minutes to understand what keys needed to be where - but software people don't use diagrams!!!  I've sat through countless meetings where a simple UML class diagram would have answered questions in minutes.  Maybe a state diagram or a good old fashioned flowchart!  But for some reason software people don't do pictures.

My question is WHY NOT?!?  I mean, cripes, it would take forever to grasp some design patterns without the diagrams.  If I hear one more developer say that, "the source code IS the model", I'm going to scream.  For heaven's sake, looking at the sheet music is NOT hearing the symphony.

anon
Thursday, June 10, 2004

"But for some reason software people don't do pictures"

That is not my experience. I can't imagine a design meeting without a huge whiteboard (or at least some beer napkins :-) )

Just me (Sir to you)
Thursday, June 10, 2004

Why not be proactive instead of reactive and stand up and say, "If you all don't mind, I'd like to draw a quick ER diagram.  I think it will really help the discussion."

Lou
Thursday, June 10, 2004

I've never been in a software design meeting without a massive whiteboard on the wall full of pictures.

muppet is now from madebymonkeys.net
Thursday, June 10, 2004

"Why not be proactive instead of reactive and stand up and say, 'If you all don't mind, I'd like to draw a quick ER diagram.  I think it will really help the discussion.'"

Yeah, I'd like to, but I work a a big company, and "THAT'S NOT THE WAY IT'S DONE HERE!"  I know, there have been plenty of aticles and threads about how to finesse the teams & managers to gradually start using better practices, but to be honest, it's just not worth my time.  Screw them; I get paid the same to sit like a log in meetings, so why should I put in the effort and stick my neck out?

anon
Thursday, June 10, 2004

Maybe they are recipe-following-bug-fixers instead of actual software developers/engineers/whatevers

Yo
Thursday, June 10, 2004

where I worked before, the DBA would not accept changes in the database, (creation, deletion of tables, indexes, changes in the structure of tables, etc) if we didn’t give him an updated ER diagram

the same happened with the applications, they would not be accepted if we didn't submit them with - at least - some specifications

Cecilia Loureiro
Thursday, June 10, 2004

How are they describing an access path to DB tables? Interactions? Processes? Just and only verbally? Not drawing? No squares? Where are those sugar clouds and iron arrows? How are they describing *anything*?

"My question is WHY NOT?!?"
May be it's because they aren't "software engineers"?

Ross Sampere
Thursday, June 10, 2004


In my group, each of us has a personal white board which is usually in use for something.


In addition, whenever we sit down to talk, we make a point of drawing pictures, sketching things out, etc.

In a project a couple years back, we did the database design on the whiteboard and steadily revised it over a week.  Everyone had a distinct color and could make/leave any comments they wanted, they just had to be ready to defend them.

It was highly educational and always let us know the status/relationship of things.

KC
Thursday, June 10, 2004

Ummm this is interesting. I am quite fond of just taking a pencil and paper before I do things.  When I worked at an ad agency I always whiteboarded stuff. I like to take something and organize it at a big level into simple, understandable parts ... they can be decomposed until the code level. But ... like the OP ... that is not the way it's done where I'm at now. People prefer talking and all *artifcats* a programmer receives is through imho duck soup word docs. They ramble. Once you start to concentrate you are forced to ask questions. I had to ask, and ask again to get screen shots. I have a feeling that maybe people are just not comfortable enough with the domain to put anything on a whiteboard. If they put a lot of words in a template it then becomes something when really it's just duck soup but if only you recognize it for what it isn't, what do you do?

I would say that of course you should use diagrams and models. I use them myself regardless of what everyone else does.

meagain
Thursday, June 10, 2004

Ditto on "let's go to the whiteboard and draw it"

Incidentally, at the place where the CEO made us put the chair back, the same CEO refused to let us put a whiteboard in our group workspace - we always had to go find a whiteboard.

If *I* was a CEO or project manager, whiteboards would go in every cube and project room. If I had the budget, the major meeting rooms would get printing whiteboards.

Philo

Philo
Thursday, June 10, 2004

"THAT'S NOT THE WAY IT'S DONE HERE!"

Anon I used to work for a company just like yours. I have a funny story to relate I call "The Rogue Whiteboard":

At this particular company we would have a lot of discussions & somtimes formal technical meetings. Whenever we had such discussions I would write on a piece of paper of if in a conference room I would draw on the whiteboard. No one else in the company saw the value in it and many times I was made fun of.

In a previous company, everyone had a whiteboard in their cubes. At this company however, only managers seemed to have them. So one day I approached my direct report and requested a whiteboard for my cube. He responded to me that the corporate policy is that only the members of management are authorized to have whiteboards in their cubes / offices.
I was very dis-heartened. The ironic thing is that the managers only use the whiteboards as calendars - dates for projects - never for technical discussions.
Anyway, one day I went to the local Target during lunch  and purchased my own white board and put it in my cube. Now I was the only non-manager in the company to have a white board. For kicks I also labeled it with a print out on the top left corner - "Rogue Whiteboard."

Gen'xer
Thursday, June 10, 2004

Very good points.

Realize, though, since 1978, we've gone through flow-charts, Data Flow Diagrams, Structure Charts, etc. to RUP and UML.  So the question I want to ask is "Diagram with what?".  Having said that, boxes indicating functions with arrows indicating data still work pretty well.

ERD diagrams seem to be pretty stable for databases (UML Studio does some nice ones).  UML is still being changed, but some sub-sets (especially as identified by Scott Ambler, Agile Modeling) do seem to lend themselves to 'back-of-the-envelope' / 'on-the-whiteboard' analysis -- class diagrams and sequence diagrams come to mind.

I agree that a picture is worth a thousand words.

AllanL5
Thursday, June 10, 2004

anon has a great point, where I work people do not use diagrams that much, and it baffles me.

And the diagrams are often just written on a whiteboard and lost.

The first thing someone does when trying to comprehend a complicated piece of code is make some little diagram... but if we had saved the diagram that the AUTHOR wrote, then every individual reader of the code wouldn't have to recreate the diagram every damn time...

Roose
Thursday, June 10, 2004

I once worked in a place that had "furniture police" straight out of Peopleware: Nothing in the cubes may protrude above the edge of the cube! Blinds in the offices must remain clipped to the bottom of the windowsill, not pulled up! Nothing unapproved to be hung on the walls!

Fortunately I was friendly enough with the facilities guys (the ones who actually did the work, not the power-drunk policy-makers) that when I bought a big whiteboard for my group, they were more than happy to break the rules and mount it on the wall.

A while back I heard that it's possible the buy the whiteboard material in bulk and cut it to size. I still have a dream of one day "wallpapering" my entire office space in whiteboard surfacing so I can scribble at will on the wall surfaces. I also need to get some of those pens that are supposed to let you scribble on the walls of your shower, since after all that's where I have some of my most productive ideas...

John C.
Thursday, June 10, 2004

Gen'xer -- I hope you took your personal rogue whiteboard with you when you left! :) 

It amazes me how office policy makers can be so dimwitted.  Let's see...  cost: N whiteboards * ~$25 each...compared to gain: 30% reduction in meeting time * X meetings...where X is substantially larger than N over time....hmmmmmm I wonder... 

But no, of course it's more important to put down the spirit of the cube dwellers by making silly rules that serve only to differentiate "management" from "employees." =)

Back on topic, I love diagrams.  Although I don't necessarily used "approve modeling languages," as when I'm whiteboarding I'm more concerned with getting the ideas out than how exactly they are drawn.  But usually my drawings represent SQL diagrams or use case flowcharts.

I only wish there were a cost effective way to save completed whiteboard drawings :(

Joe
Thursday, June 10, 2004

> I agree that a picture is worth a thousand words.

That depends on how dense the picture is; if it's depicting the interactions of only three or four things, then 1000 words of text may well contain more information.

Christopher Wells
Thursday, June 10, 2004

> I get paid the same to sit like a log in meetings, so why should I put in the effort and stick my neck out?

Maybe you would increase the productivity of you and your fellow workers.
Maybe make your department look good.
Maybe make your boss look good.
Maybe the project would get done quicker.
Maybe there would be less meetings.
Maybe your stress level would be lower.
Maybe your colleagues would respect your opinion.
Maybe you would educate the non-programmers around you.
Maybe you can increase your companies bottom line.

If you do this consistently across all aspects of your working life, maybe you would get a raise.

Then again. Maybe you are just too cynical to be dealing with people in the real world. Go back and program your computer.

--
ee

eclectic_echidna
Thursday, June 10, 2004

THEN AGAIN, remember the movie Stargate, where Daniel started writing in the sand, and the chieftain wiped out the wriging. To obviously show that writing was forbidden.

Is someone going to do in the meeting, start erasing the image as you create it?  Forbidden, FORBIDDEN, AHHHHHHHHHHHHH

I would love to work there, oh, the trouble I would cause… he he he

--
ee

eclectic_echidna
Thursday, June 10, 2004

I think going crazy with a bunch of charts, diagrams and all kinds of cool do-dads is a not really a productive thing.

Some people just LOVE playing with drawing tools.

However, when it comes to database stuff, then boy, having a ER diagram REALLY helps. You can have a trough time wading through someone else’s code.

However, you can’t really modify, or change someone’s code, or even add new code unless you understand the relationships between the data tables that you are gong to use. Thus, even if I hate the code I am looking at and decide to write my own routines, I STLL must have a understanding of the data model.

Without this understanding, little, or no code can be written, nor can existing code be changed.

I have little trouble when I see some work that does not have a bunch of cool UML diagrams for objects and the like. That is often a luxury in this world that projects don’t have.

However, no ER diagrams for database tables? They are an absolute must in IMHO.

Further most systems have er tools that not only result in the diagram, but enforce referential integrity to boot. So, you get the diagram part for free, and in fact the drawing process actually gives  you the enforced relations. This is the only way to fly when it comes to modern software development.

If the application only has a few tables, like 3, or 4..then you can hold that stuff in your head.

However, in virtually ALL projects I do, and even those small ms-access projects, the first pages of documentation are the ER diagrams. I  have a binder for each project I do. and the first thing that goes in is the ER model).

Further, do you know how to read the models that your company uses? (you can use whatever, but how does your model communicate the design?).

I am going to give you quick rundown of some of the Sherlock homes type stuff you learn from a ER diagram.

The first diagram here is simply a table relationship model I did in Visio. Fields, and what not where NOT important. However, just getting the general design down on paper was the real goal here (hint, when designs get very compliex..just work with table relations. and don’t worry about fields…best trick I ever learned).

Here is this basic design diagram

http://www.attcanada.net/%7ekallal.msn/Articles/PickSql/Appendex1.html

The above general design is then turned into the real thing. Here is the resulting Er diagram.

http://www.attcanada.net/%7ekallal.msn/Articles/PickSql/Appendex2.html

A few very important things can be seen on the above diagram.

Note how the relation line is drawn between table tblBgroup and  tblPayments (they are up at the top in this diagram). Note the little arrow head, and the omega sign. In these tools, this means a enforced left join. You need to learn how this looks with what ever your tools your team will use. This arrow head means that the original designers of this system allow the parent table to have records added, but not necessarily have child records added. This makes sense. In plain English, the above means that means that a person can be booked in a tour (tblBgroup), but NOT yet have made payments for that tour (tblPayments).

This makes perfect sense, and your diagrams you give me BETTER reflect this design assumption..

However, take look at the join line from table tblBooking to the above tblBgroup. You will notice no arrow head. This is a inner join. This means that the designers (in code, and in data) assume that when you add a record to tblBooking, then you MUST add a record to tblBgrouup.

In plain English this means that if you make a booking to a tour, then you MUST include people (tblBgroup) in that tour! (again, this makes perfect sense in both English, and in terms of the design assumptions made). 

So, your diagram better reflect this. When I am hiring you, you better be able to explain the above to me, as this is one of my questions.  And, to be fair, I will let you pick your favorite top database ER diagram that you are supposed to be familiar with. (I have the diagram in several flavors). So,  I will let  you tell me what your favorite ER tool is, and procedure to pull out of the file folder that SAME er diagram for that tool.

Most diagramming tools allow you to deduct the above assumptions that the designers of the system made.

Of course, in most cases (and applications in general), a child record does NOT need to be added. And, if you take a look at the diagram, about 90% or more of the joins are thus defined as left joins.

I can’t tell you how often I seen ER diagrams NOT used as a design document, and even more often how the above assumptions about the design are NOT communicated correctly.

How can the developers possibility know what your assumptions are without such diagrams? How can a developer even decide to add a record to a table without knowing that other reocrds are required, or it is optional?

This is really a sad thing.

ER tools are very good today, and in fact most of the time fun to use.

So, for some fun effort, you get a resulting cool looking diagram that is by FAR and away the most useful document you can have for a project.


Albert D. Kallal
Edmonton, Alberta Canada
kallal@msn.com
http://www.attcanada.net/~kallal.msn

Albert D. Kallal
Thursday, June 10, 2004

Interesting thoughts, eclectic_echidna, but I disagree...

*      *      *      *
>> "Maybe you would increase the productivity of you and your fellow workers."
>> "Maybe make your department look good."
>> "Maybe make your boss look good."
>> "Maybe you can increase your companies bottom line."
>> "Maybe you would educate the non-programmers around you."

These things benefit the corporation and don't benefit me in the least.  Why don't I just give back half my paycheck so the CIO can get that new Lincoln Navigator he's had his eye on?

*      *      *      *
>> "Maybe the project would get done quicker."

If the project got done quicker, they'd just give me more work to do without any extra salary.

*      *      *      *
>> "Maybe your stress level would be lower."

My stress level's never been lower.  I stressed out when I CARED about the software.  If the company doesn't care about its software, why should I?

*      *      *      *
>> "If you do this consistently across all aspects of your working life, maybe you would get a raise."

I was hired in 2000 at the height of the bubble years.  I'm locked in at that super-inflated rate; that's why I still work here.  I'll never, ever get a raise for the rest of my life.

anon
Thursday, June 10, 2004

Albert D. Kallal,
Yep, I agree.  ER diagrams aren't worth a thousand words - they're worth a THOUSAND THOUSAND words.  My preference is ERWin.  It rocks!

anon
Thursday, June 10, 2004

ERWin for ER/Diagrams is nice if you can get someone else to buy it for you. :-)

Philo

Philo
Friday, June 11, 2004

So if we let Kallal post images maybe he wouldn't feel the need to write a novel for each post?

(That one was pretty darn close to 1000 words.  I wonder what the picture would have been.)

Wally
Friday, June 11, 2004

"I hope you took your personal rogue whiteboard with you when you left! :) "

Don't worry Joe I still have the "Rogue Whiteboard" and it gets used very often!!!!

:-)

Gen'xer
Friday, June 11, 2004

Joe,

>I only wish there were a cost effective way to save completed whiteboard drawings :(

I've used the demo version of Whiteboard Photo. Very impressive. I think the price has gone up over the last few months though  :-(

No so impressed with on-line ordering only being available to USA.

http://www.polyvision.com/products/wbp.asp

Ian H.
Friday, June 11, 2004

Why? Because it is far easier to CYA using words. Obfuscation in the name of clarity. Yes, that is right.

Blame it on lawyers. Blame it on the 'I WANT TO KNOW WHO IS RESPONSIBLE' bosses, blame it on anything. If it is using words, I stand a better chance re-explaining to suit the current inquisition what I write, than what I draw.

KayJay
Friday, June 11, 2004

"I once worked in a place that had "furniture police" straight out of Peopleware: Nothing in the cubes may protrude above the edge of the cube!"

Whoa, a Cube Nazi!

Steve-O
Friday, June 11, 2004

"I only wish there were a cost effective way to save completed whiteboard drawings :("

Try paper...

Wally
Friday, June 11, 2004

A cost effective way of saving whiteboard drawings - surely a cheap digital camera?

Cheapskate
Monday, June 14, 2004

*  Recent Topics

*  Fog Creek Home