Software Engineering - Need advise on Software Design Document development

Author

Need advise on Software Design Document development

Ramesh

2006-05-31, 10:01 pm

Hey guys,

I am a reasearch software engineer working in LIDAR field. During my
research process I have created nice piece of software and it is quite
large. Now to be organized, I am thinking of creating design doc for my
software to keep track of whats happening, what classes and interfaces
and dlls present in my software module. Can someone suggest me which
way to go on this? I have limited time to create this, do you guys
think it is easy to go with a sample design or any other ideas....

Thanks a lot.

Phlip

2006-05-31, 10:01 pm

Ramesh wrote:

> I am a reasearch software engineer working in LIDAR field. During my
> research process I have created nice piece of software and it is quite
> large. Now to be organized, I am thinking of creating design doc for my
> software to keep track of whats happening, what classes and interfaces
> and dlls present in my software module. Can someone suggest me which
> way to go on this? I have limited time to create this, do you guys
> think it is easy to go with a sample design or any other ideas....

There are two schools of thought here.

Both of them say:

- use UML to draw pictures of the code's structure
- use rampant Unit Tests to document code behavior

Your ratio of test to code should be >3:1. That makes other details easy.
Some tests can be very literate, and can output illustrations of the code's
activity.

--
Phlip
[url]http://c2.com/cgi/wiki?Z

Land[/url] <-- NOT a blog!!!

James Bond 007

2006-05-31, 10:01 pm

"Ramesh" <ramesh.sridharan@gmail.com> wrote in message =
news:1149094490.715035.214390@h76g2000cwa.googlegroups.com...
> Hey guys,
>=20
> I am a reasearch software engineer working in LIDAR field. During my
> research process I have created nice piece of software and it is quite
> large. Now to be organized, I am thinking of creating design doc for =
my
> software to keep track of whats happening, what classes and interfaces
> and dlls present in my software module. Can someone suggest me which
> way to go on this? I have limited time to create this, do you guys
> think it is easy to go with a sample design or any other ideas....
>=20
> Thanks a lot.
>

Ramesh,

Better late than never. But what you are doing now is reverse =
engineering. You wrote the software, and now you want to write the =
design document. You should have written the design document first. =
But as I said, better late than never. Many programmers wouldn't bother =
with it. I would start with a high level overview of what the software =
does and reference any requirements that you had or why you wrote the =
software. Then just go through the code and document the modules, =
classes, and interfaces that you are using.

James

David Lightstone

2006-05-31, 10:01 pm

"Ramesh" <ramesh.sridharan@gmail.com> wrote in message
news:1149094490.715035.214390@h76g2000cwa.googlegroups.com...
> Hey guys,
>
> I am a reasearch software engineer working in LIDAR field. During my
> research process I have created nice piece of software and it is quite
> large. Now to be organized, I am thinking of creating design doc for my
> software to keep track of whats happening, what classes and interfaces
> and dlls present in my software module. Can someone suggest me which
> way to go on this? I have limited time to create this, do you guys
> think it is easy to go with a sample design or any other ideas....
>

See the book by Paul Clement et al - Documenting Software Architectures

> Thanks a lot.
>

S Perryman

2006-06-01, 4:03 am

"Phlip" <phlipcpp@yahoo.com> wrote in message
news:QXjfg.2698$VE1.2020@newssvr14.news.prodigy.com...

> Ramesh wrote:

[color=darkred]
> There are two schools of thought here.

> Both of them say:

> - use UML to draw pictures of the code's structure
> - use rampant Unit Tests to document code behavior
>
> Your ratio of test to code should be >3:1. That makes other details easy.

A ratio like that is symptomatic of a poor test regime.

Is your TDD roman numerals example typical of the test infrastructure that
your development method produces (if so, it explains a lot) ??

Regards,
Steven Perryman

swengineer001@gmail.com

2006-06-01, 7:03 pm

Ramesh wrote:
> Hey guys,
>
> I am a reasearch software engineer working in LIDAR field. During my
> research process I have created nice piece of software and it is quite
> large. Now to be organized, I am thinking of creating design doc for my
> software to keep track of whats happening, what classes and interfaces
> and dlls present in my software module. Can someone suggest me which
> way to go on this? I have limited time to create this, do you guys
> think it is easy to go with a sample design or any other ideas....
>
> Thanks a lot.

Sounds like you are doing this backwards to me but since you already
have the software you may be able to achieve what you want by using a
tool lik Doxygen. It is available for free and does a good job of
allowing you to navigat the code easily. There are plugins available to
do diagraming and pull documentation from the code as well.

I am curious why you would not have developed a design prior to, or at
least in tandem with, the development of the code? It is good that you
want to do it now but the purpose of a design is rendered moot by doing
it after the code is complete.

David

2006-06-05, 10:02 pm

Hello Ramesh,

On Wed, 31 May 2006 16:54:50 UTC, "Ramesh" <ramesh.sridharan@gmail.com> wrote:

> Hey guys,
>
> I am a reasearch software engineer working in LIDAR field. During my
> research process I have created nice piece of software and it is quite
> large. Now to be organized, I am thinking of creating design doc for my
> software to keep track of whats happening, what classes and interfaces
> and dlls present in my software module. Can someone suggest me which
> way to go on this? I have limited time to create this, do you guys
> think it is easy to go with a sample design or any other ideas....
>
> Thanks a lot.

It sounds like you'd like to formalize the design documentation
and then document the interfaces that are useful. This is very
useful information to others and people on your team. I much
prefer this type of description to the rather ugle UML documents
I've seen used by other teams.

Basically I like to just write a short formal document that is
very close to what I'd do "up front" or as a "white board"
example of my project if I was to try to train someone about
it. What do the major building blocks look like and how do
they fit together? For application designs, I'll include
a list of processes, threads, and so on and tell about what
they do. Finally I describe the interfaces from the outside
and how to use them.

The internals are usually documented well as part of the
system/code, so that doen't need to be stated again. Generally
the above information cna be the building blocks for a patent,
design notes, or description of how your product fits into
other systems. Most people forget this description and dwell
on the internal stuff.

Yes, Phlip has a point on some things, but he hasn't said
much about how to re-engineer the project from scratch without
a working example. I've seen far too many groups that have
no idea how their components fit together or even what it
does. A simple "cocktail napkin" diagram along with a little
description will often help a newcomer envision what the
product does and how the parts interact. It should be nearly
enough that you could build the product from scratch. Why?
Say that you have an aging system that no one really
understands. If you can't rework it, perhaps rebuilding part
of it is a solution. It helps to know what the fabric of
the design really is and how the pieces interact. That doesn't
mean the new work would be complete or the same, but it would
go a long way towards allowing the functionality to be rebuilt
and reused.

For instance, in describing an email client you could start with
the pointers to SMTP, POP3, and MAPI protocols. Then the
interfaces you expose to the user. Then perhaps how the product
fits together.

Whatever the documentation you decide upon, it should reflect
what your team and users would expect to have. If they need
pointers to lots of interface documents, have it. If they
understand UML, use it. Just remember that we don't all have
the same background and experience and a too detailed document
just hides all the real content the reader is looking for when
they start reading it.

David

Sponsored Links