What makes a good design document?

Tom Dunne

My background is infrastructure/databases, but I have a reasonable understanding of the SDLC. I'm supervising a couple of student projects that are primarily 3-tier, web apps. Nothing too taxing, mostly 2nd and 3rd year projects.

When they start, I always use the house analogy - you don't start building a house until you have your plans, same goes for a development project. So we put a lot of emphasis on the analysis and design phase (students have studied programming/databases and Systems Analysis + Design prior to this).

So what do you think should be in the design document? I'm told data flow diagrams are so last century.

I'm assuming functional/non-functional requirements, architecture diagram(s), event state diagrams, class diagrams, that kind of stuff?

CreepingDeath

Tom Dunne wrote: »

I'm assuming functional/non-functional requirements, architecture diagram(s), event state diagrams, class diagrams, that kind of stuff?

A requirements document should be completely independent of design.
It should never mention languages, databases, storage types etc.... just what they want the system to do.
Something that a QA department could then take and apply against the finished product to check that all the high level requirements were met.

A design document should be at a level that you can hand it to another developer and they can implement it.
That means clearly defined inputs and outputs of the system, high level module interactions, how to respond to errors/bad input etc.
It depends on how large the piece of work is.

Then, you might use UML sequence diagrams and class diagrams to explain the functionality.

The Corinthian

OT, but I'm reminded of this old one:

Documentation is like sex. When it's good, it's really, really good. And when it's bad, it's still better than nothing.

Tom Dunne

CreepingDeath wrote: »

A requirements document should be completely independent of design.

I appreciate that, but in an academic environment where this not their final year project, I am attempting to ensure that they capture the vital elements in one document. A context expert (not me) will be correcting it. So it's more of an administration thing than anything else.

CreepingDeath wrote: »

It should never mention languages, databases, storage types etc.... just what they want the system to do.

Yeah, that's a great point and I think it is something the Analysis/Design people have hammered into the students. They do seem to be aware of this.

The Corinthian wrote: »

OT, but I'm reminded of this old one:

Documentation is like sex. When it's good, it's really, really good. And when it's bad, it's still better than nothing.

I'm not so sure I can share that with my students.

awec wrote: »

IMO you need to ask yourself what the goal of your dev spec is to want diagrams, flow charts etc in it.

Basically, to ensure that they have a good understanding of what they are attempting to build. A key factor here is that these students are learning in a second language (i.e. English), so rather than write walls of text, I find that diagrams are a good way to determine their understanding. Plus, in a lot of cases, it is good practice. Once they have a high-level overview, they can then start into the design proper, firing up Rational Rose and the like.

awec wrote: »

If so I would say code reviews are a more effective method here and that the dev spec should just ensure that the developer isn't going down the completely wrong path.

That's my job, really, to ensure they stay on the correct path.

awec wrote: »

Of course this is going to vary a lot from system to system and company to company. If you're writing software that manages bank accounts you're obviously going to have a much more rigorous process than someone working on some random website.

Yeah, these projects are going to be fairly straight forward, nothing too taxing. The key thing here is they all have a real life client - somebody who is essentially technically illiterate, but knows the business processes backwards. Just the like real world.


Some excellent points raised, thanks guys.

awec

Ha, I deleted my post cause I wanted to re word it and had to run to a meeting. Ninja like quoting there Tom!

amen

I'm told data flow diagrams are so last century

Really ? I still use these. They are invaluable for tracing how the data moves through the system and highlighting points of failure.

Also handy when dealing with customers.

croo

After SSADM came many competing OO processes & notations (I used Yourdan/Coad myself), but it was a mess really with everyone having their own approach. So after a few years of chaos these were all merged into the Unified Software Development Process which relied heavily on the new Unified Modelling Language (UML) diagramming techniques. So if you go "by the book", this is it.

The first book to describe the process was titled The Unified Software Development Process (ISBN 0-201-57169-2) and published in 1999 by Ivar Jacobson, Grady Booch and James Rumbaugh.

While that book goes into great detail re their new process, I found a book called Applying UML & Patterns from a guy called Craigh Larman to be much more helpful to me in the real world.

Looking at that website I see a quote from Martin Fowler

“People often ask me which is the best book to introduce them to the world of OO design. Ever since I came across it Applying UML and Patterns has been my unreserved choice.”
—Martin Fowler, author, UML Distilled and Refactoring

I liked everything Martin wrote so I would take that as high praise!

Today with the advent of Agile & XP even a lot of that is looking dated. But even so, it does no harm to learn all the varying approaches... even SSADM (I guess). I loved the simpicitly of DeMarco's SSADM but I honestly haven't seen a DFD since the early 90s myself.

I would use the new approaches for one of the projects (the last probably) using some of the new Agile approaches... if it were me.

fergalr

Really kind of surprised at all the heavyweight stuff here:

Then, you might use UML sequence diagrams and class diagrams to explain the functionality.

Once they have a high-level overview, they can then start into the design proper, firing up Rational Rose and the like.

Are the students on a special course for designing avionics or something? Because a lot of general modern software development seems to be using much lighter weight processes. I'd go so far as to say that for much business software, the more regimented upfront approaches have failed. People were concluding this 15 years ago?

Tom Dunne

amen wrote: »

Really ? I still use these. They are invaluable for tracing how the data moves through the system and highlighting points of failure.

Good. Thank you. I'm out of industry over 7 years, so I thought I was losing it.

amen wrote: »

Also handy when dealing with customers.

And students whose first language is not English.

fergalr wrote: »

Are the students on a special course for designing avionics or something? ?

No. These projects are what we call "special project" - elective courses taken outside their main, prescribed courses, that earn credits towards the degree. A big complaint from employers (both in Ireland and abroad) is that graduates lack real-world skills. This particular course is designed to make the experience as "real world" as possible, including a real client (a non-academic staff member who wants a software app developed). Here's another example of such a project students have completed.

fergalr

Tom Dunne wrote: »

No. These projects are what we call "special project" - elective courses taken outside their main, prescribed courses, that earn credits towards the degree. A big complaint from employers (both in Ireland and abroad) is that graduates lack real-world skills. This particular course is designed to make the experience as "real world" as possible, including a real client (a non-academic staff member who wants a software app developed). Here's another example of such a project students have completed.

I remember that thread - cool project.

Its just, I don't know anyone good who would set out to build a project anything like that in the real world by starting off with UML sequence diagrams, rational rose etc.

Building plane avionics and banking databases, maybe, but not User Interfaces for kiosk computers - thats not how this stuff gets built.

matrim

Tom Dunne wrote: »

No. These projects are what we call "special project" - elective courses taken outside their main, prescribed courses, that earn credits towards the degree. A big complaint from employers (both in Ireland and abroad) is that graduates lack real-world skills. This particular course is designed to make the experience as "real world" as possible, including a real client (a non-academic staff member who wants a software app developed). Here's another example of such a project students have completed.

If that's the goal maybe put some focus on the use of tools such as source control (git).

Have the students document the code with javadoc(or similar) and use tools such as doxygen to get design and code documentation post coding.

croo

fergalr wrote: »

Its just, I don't know anyone good who would set out to build a project anything like that in the real world by starting off with UML sequence diagrams, rational rose etc.

Well you could sign up for Tom's course then! When is it stariing Tom

More seriously, I suppose the need in this case is the need to learn modeling rather than a complex problem needing to be modeled.

I would echo what fergalr says re using some of the more modern light weight (lean) approaches... but I suggest it in be in addition to rather than instead of.

PS. I haven't used any of the big project techniques in years but when I did I always started with Use Case diagrams!

Tom Dunne

croo wrote: »

When is it stariing Tom

It's just started - you still have time.

It is actually a great course. No classes, no instruction, regular meetings with the supervisor and the client. The student has to apply what he/she has learned in all the other classes and apply them to a real-world project, with real-world clients.

croo wrote: »

More seriously, I suppose the need in this case is the need to learn modeling rather than a complex problem needing to be modeled.

That's the essence of it. It's not just the modelling, but also the application of that model to develop at least a working prototype of the project which can be properly developed later in, say, the final year project.

croo wrote: »

I would echo what fergalr says re using some of the more modern light weight (lean) approaches... but I suggest it in be in addition to rather than instead of.

Agreed. But there is always the conflicting priorities of what we can actually cram into a single-semester course such as this, while ensuring we meet the learning outcomes and being fair to the students.

croo wrote: »

PS. I haven't used any of the big project techniques in years but when I did I always started with Use Case diagrams!

Yeah, they are in there (or at least, will be) somewhere.