By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
425,563 Members | 1,066 Online
Bytes IT Community
+ Ask a Question
Need help? Post your question and get tips & solutions from a community of 425,563 IT Pros & Developers. It's quick & easy.

Neat database diagrammatic documentation scheme

P: n/a
Recently, I've been working on an Access application that is supposed to be
the prototype for a larger system that will be developed by a team using
Oracle tools, etc. As such, everything I do must not only work, but it must
be easy to understand and duplicate.

Now, obviously one of the goals should be to avoid anything too "clever", but
I found that the to balance all the requirements of the system, I needed a
schema that could only be described as "clever", so it requires some
explanation for those who will have to reimplement it. Specifically, it could
use some visuals, and I don't just mean schema diagrams.

Another requirement I've learned to apply to any documentation is that the
closer it is physically connected to the code, the better. The less closely
it is tied, the less likely it is to be seen and used, and the less likely it
is to be maintained and useful. Ideally, then, the diagrams need to be
embedded in the front-end MDB itself. I could use OLE embedded Visio
diagrams, but Visio is not available on every system which makes the content
less useful and less maintainable. Word Art and Excel Diagrams are not
powerful enough to do fancy diagrams, and also have them be easy to maintain.
What do do?

The solution I finally came up with was to invent a graphical idiom for my
diagrams that's so bloody simple that you can create and modify the diagrams
easily using nothing more than Access label controls and lines. When I showed
the resulting diagrams to the managers, they almost instantly understood what
the diagrams were intended to convey even though they had never seen this
style of diagram before.

As an aside, one manager did ask me what the diagram type was called, though,
and I said I didn't know if it had a name. He's now calling them Steve
diagrams. Actually, they're a bit similar to Venn diagrams, but not exactly.

Here's how it works...

When you have a foreign key relationship, you can think of that as a
collection container. The table on the 1-side (the primary key side) of the
relationship "contains" one or more of the items on the many-side (the foreign
key side), so you draw a big box (label with a border) for the "container"
table and a smaller box inside it for the "collection" table that's
"contained" within.

+--------------------+
| Invoice |
| |
| +--------------+ |
| | Invoice Line | |
| | | |
| +--------------+ |
+--------------------+

Note that since these diagrams might be shown to management, the label
captions might name the concepts in plain language and not exactly follow the
table names, but it should always be obvious which tables they must be
referring to. For instance, the diagram above might be describing tables
called tblInvoice and tblInvoiceLine.

Now, if you have, say, a many-to-many relationship, that's 2 tables, each
containing items in the junction table that are also contained by records in
the other m-m table. In this case, you draw the many-to-many table boxes
adjacent to each other, but not overlapping (don't align the corners, or the 2
rectangles will seem to be one bisected rectangle), and draw the junction
table as a smaller rectangle overlapping the boundary between the 2 m-m
tables. It's fairly trivial to extend this to model some much more
interesting constructs.

+----------+
| Contact +----------+
| | Role |
| +--------------+ |
| | Contact/Role | |
| +--------------+ |
| | |
+----------+ |
+----------+

Of course, no terribly complex model can be completely illustrated in a single
diagram of this form, and that's fine. You just make a diagram for each
significant concept in the model, and many tables will appear on different
diagrams in different roles. Concepts that are more easily understood simply
by looking at the ERD, of course, don't need a diagram at all, assuming your
ERD can be laid out reasonably well in the Relationships pane.

Other details of the scheme:
- If you need to represent constraints (enforced by schema or just business
rules) on the number of related records such as 1-to-1 or 1-to-2, add a label
with a light-grey border overlapping the boundary line that says "1 to 1" or
whatever.
- If you really have to show a relationship that doesn't fit in the
hierarchical box model, draw a line from one box to the other with an arrow
head pointing to the many-side table box. Keep these lines vertical or
horizontal, so it's easy to make and arrow head out of 2 little lines.
- You can use left and right text alignment and/or insert line breaks to move
the label caption out of the way of other overlapping label boxes.
- If it's impossible to show a table overlapping the rectangles you need
without also intersecting another rectangle it does -not- relate to, put a
label with an X on the boundary to indicate this fact.
Nov 13 '05 #1
Share this Question
Share on Google+
8 Replies


P: n/a
> Another requirement I've learned to apply to any documentation is that the
closer it is physically connected to the code, the better. The less closely
it is tied, the less likely it is to be seen and used, and the less likely it
is to be maintained and useful.
In writing the documentation for the classes on my site, I devised an
extraction utility and put all documentation in the class code itself
(as comments of course). Several properties even arise from the code and
can be retrieved by the extractor without intervention.

I didn't finish the extractor then because I only had so many classes to
document (what is it? three? four?) but it might well be worth the effort.

It would be the best if the code could only come to being out of the
documentation. I tend to work that way as much as possible but I cannot
see an automation. Would not be good for my income too :-)
The solution I finally came up with was to invent a graphical idiom for my
diagrams that's so bloody simple that you can create and modify the diagrams
easily using nothing more than Access label controls and lines. When I showed
the resulting diagrams to the managers, they almost instantly understood what
the diagrams were intended to convey even though they had never seen this
style of diagram before.


That is completely wonderful. !.
I can apply this immediately. The name Jorgensen speaks more to me
than does Steve, though, I will see if I can spread this :-)

--
Bas Cost Budde, Holland
http://www.heuveltop.nl/BasCB/msac_index.html
I prefer human mail above automated so in my address
replace the queue with a tea
Nov 13 '05 #2

P: n/a
On Tue, 30 Nov 2004 13:57:18 +0100, Bas Cost Budde <b.*********@heuvelqop.nl>
wrote:
Another requirement I've learned to apply to any documentation is that the
closer it is physically connected to the code, the better. The less closely
it is tied, the less likely it is to be seen and used, and the less likely it
is to be maintained and useful.
In writing the documentation for the classes on my site, I devised an
extraction utility and put all documentation in the class code itself
(as comments of course). Several properties even arise from the code and
can be retrieved by the extractor without intervention.


Nice. Is it sort of modelled after JavaDoc?
I didn't finish the extractor then because I only had so many classes to
document (what is it? three? four?) but it might well be worth the effort.

It would be the best if the code could only come to being out of the
documentation. I tend to work that way as much as possible but I cannot
see an automation. Would not be good for my income too :-)


I find the next best thing is to just code by intention, so that the code
almost reads like documentation. First write a procedure as a few lines of
psuedocode steps, make the steps into procedure names, then implmenet
procedure stubs until the code compiles, then write those procedures using the
same techniques. When something gets hard to code in that simple manner,
refactor the code until it isn't (e.g. split up a class, move variables from
local to class or vice verse, etc.) Writing code this way also helps avoid
producing ugly things like overly nested control structures.
The solution I finally came up with was to invent a graphical idiom for my
diagrams that's so bloody simple that you can create and modify the diagrams
easily using nothing more than Access label controls and lines. When I showed
the resulting diagrams to the managers, they almost instantly understood what
the diagrams were intended to convey even though they had never seen this
style of diagram before.


That is completely wonderful. !.
I can apply this immediately. The name Jorgensen speaks more to me
than does Steve, though, I will see if I can spread this :-)


Cool - I hope it is helpful.
Nov 13 '05 #3

P: n/a
Steve Jorgensen wrote:
can be retrieved by the extractor without intervention.
Nice. Is it sort of modelled after JavaDoc?


Don't know (twice: JavaDoc, and hence if it looks like it)
I find the next best thing is to just code by intention, so that the code
almost reads like documentation.


Often I don't find that enough. I can see what it does but not why I
thought it out that way in the first place. Well, that's what comments
are for, right?

--
Bas Cost Budde, Holland
http://www.heuveltop.nl/BasCB/msac_index.html
I prefer human mail above automated so in my address
replace the queue with a tea
Nov 13 '05 #4

P: n/a
I just realized some cases I left out of the previous message...

Let's say tblProduct has an optional foreign key to tblColor. The Product box
is shown ot top because its items are contained, but it is shown not
completely within the boundary of color because it is not completely
contained.

+---------+
| Color |
| |
| +---------+
| | Product |
| +---------+
+---------+

Now, let's say we want to show a many-to-many between invoice lines and
discounts. Invoice Line is already contained within Invoice, so we keep it
fully contained, but move it adjacent to one edge, so we can add the
overlapping m-m table from Invoice Line to Discount.

+-----------------+
| Invoice |
| +------------------+
| +--------------+ Discount |
| | Invoice Line | |
| | +----------+--------------+ |
| | | Invoice Line / Discount | |
| | +----------+--------------+ |
| +--------------+ |
+-----------------+ |
+------------------+

On Tue, 30 Nov 2004 09:08:33 GMT, Steve Jorgensen <no****@nospam.nospam>
wrote:
Recently, I've been working on an Access application that is supposed to be
the prototype for a larger system that will be developed by a team using
Oracle tools, etc. As such, everything I do must not only work, but it must
be easy to understand and duplicate.

Now, obviously one of the goals should be to avoid anything too "clever", but
I found that the to balance all the requirements of the system, I needed a
schema that could only be described as "clever", so it requires some
explanation for those who will have to reimplement it. Specifically, it could
use some visuals, and I don't just mean schema diagrams.

Another requirement I've learned to apply to any documentation is that the
closer it is physically connected to the code, the better. The less closely
it is tied, the less likely it is to be seen and used, and the less likely it
is to be maintained and useful. Ideally, then, the diagrams need to be
embedded in the front-end MDB itself. I could use OLE embedded Visio
diagrams, but Visio is not available on every system which makes the content
less useful and less maintainable. Word Art and Excel Diagrams are not
powerful enough to do fancy diagrams, and also have them be easy to maintain.
What do do?

The solution I finally came up with was to invent a graphical idiom for my
diagrams that's so bloody simple that you can create and modify the diagrams
easily using nothing more than Access label controls and lines. When I showed
the resulting diagrams to the managers, they almost instantly understood what
the diagrams were intended to convey even though they had never seen this
style of diagram before.

As an aside, one manager did ask me what the diagram type was called, though,
and I said I didn't know if it had a name. He's now calling them Steve
diagrams. Actually, they're a bit similar to Venn diagrams, but not exactly.

Here's how it works...

When you have a foreign key relationship, you can think of that as a
collection container. The table on the 1-side (the primary key side) of the
relationship "contains" one or more of the items on the many-side (the foreign
key side), so you draw a big box (label with a border) for the "container"
table and a smaller box inside it for the "collection" table that's
"contained" within.

+--------------------+
| Invoice |
| |
| +--------------+ |
| | Invoice Line | |
| | | |
| +--------------+ |
+--------------------+

Note that since these diagrams might be shown to management, the label
captions might name the concepts in plain language and not exactly follow the
table names, but it should always be obvious which tables they must be
referring to. For instance, the diagram above might be describing tables
called tblInvoice and tblInvoiceLine.

Now, if you have, say, a many-to-many relationship, that's 2 tables, each
containing items in the junction table that are also contained by records in
the other m-m table. In this case, you draw the many-to-many table boxes
adjacent to each other, but not overlapping (don't align the corners, or the 2
rectangles will seem to be one bisected rectangle), and draw the junction
table as a smaller rectangle overlapping the boundary between the 2 m-m
tables. It's fairly trivial to extend this to model some much more
interesting constructs.

+----------+
| Contact +----------+
| | Role |
| +--------------+ |
| | Contact/Role | |
| +--------------+ |
| | |
+----------+ |
+----------+

Of course, no terribly complex model can be completely illustrated in a single
diagram of this form, and that's fine. You just make a diagram for each
significant concept in the model, and many tables will appear on different
diagrams in different roles. Concepts that are more easily understood simply
by looking at the ERD, of course, don't need a diagram at all, assuming your
ERD can be laid out reasonably well in the Relationships pane.

Other details of the scheme:
- If you need to represent constraints (enforced by schema or just business
rules) on the number of related records such as 1-to-1 or 1-to-2, add a label
with a light-grey border overlapping the boundary line that says "1 to 1" or
whatever.
- If you really have to show a relationship that doesn't fit in the
hierarchical box model, draw a line from one box to the other with an arrow
head pointing to the many-side table box. Keep these lines vertical or
horizontal, so it's easy to make and arrow head out of 2 little lines.
- You can use left and right text alignment and/or insert line breaks to move
the label caption out of the way of other overlapping label boxes.
- If it's impossible to show a table overlapping the rectangles you need
without also intersecting another rectangle it does -not- relate to, put a
label with an X on the boundary to indicate this fact.


Nov 13 '05 #5

P: n/a
On Tue, 30 Nov 2004 17:07:32 +0100, Bas Cost Budde <b.*********@heuvelqop.nl>
wrote:
Steve Jorgensen wrote:
can be retrieved by the extractor without intervention.


Nice. Is it sort of modelled after JavaDoc?


Don't know (twice: JavaDoc, and hence if it looks like it)
I find the next best thing is to just code by intention, so that the code
almost reads like documentation.


Often I don't find that enough. I can see what it does but not why I
thought it out that way in the first place. Well, that's what comments
are for, right?


Agreed - "why" information one of the primary appropriate uses for comments.
Nov 13 '05 #6

P: n/a
After doing this, turn the comments

' Get the id from the employee table

into

errText = "Get the id from the employee table"

and use the errText variable in my error handler

Darryl Kerkeslager
"Steve Jorgensen" <no****@nospam.nospam> wrote:
I find the next best thing is to just code by intention, so that the code
almost reads like documentation. First write a procedure as a few lines of psuedocode steps, make the steps into procedure names, then implmenet
procedure stubs until the code compiles, then write those procedures using the same techniques.

Nov 13 '05 #7

P: n/a

"Steve Jorgensen" <no****@nospam.nospam> wrote in message
news:di********************************@4ax.com...
Recently, I've been working on an Access application that is supposed to
be
the prototype for a larger system that will be developed by a team using
Oracle tools, etc. As such, everything I do must not only work, but it
must
be easy to understand and duplicate.

Now, obviously one of the goals should be to avoid anything too "clever",
but
I found that the to balance all the requirements of the system, I needed a
schema that could only be described as "clever", so it requires some
explanation for those who will have to reimplement it. Specifically, it
could
use some visuals, and I don't just mean schema diagrams.

Another requirement I've learned to apply to any documentation is that the
closer it is physically connected to the code, the better. The less
closely
it is tied, the less likely it is to be seen and used, and the less likely
it
is to be maintained and useful. Ideally, then, the diagrams need to be
embedded in the front-end MDB itself. I could use OLE embedded Visio
diagrams, but Visio is not available on every system which makes the
content
less useful and less maintainable. Word Art and Excel Diagrams are not
powerful enough to do fancy diagrams, and also have them be easy to
maintain.
What do do?

The solution I finally came up with was to invent a graphical idiom for my
diagrams that's so bloody simple that you can create and modify the
diagrams
easily using nothing more than Access label controls and lines. When I
showed
the resulting diagrams to the managers, they almost instantly understood
what
the diagrams were intended to convey even though they had never seen this
style of diagram before.

As an aside, one manager did ask me what the diagram type was called,
though,
and I said I didn't know if it had a name. He's now calling them Steve
diagrams. Actually, they're a bit similar to Venn diagrams, but not
exactly.

Here's how it works...

When you have a foreign key relationship, you can think of that as a
collection container. The table on the 1-side (the primary key side) of
the
relationship "contains" one or more of the items on the many-side (the
foreign
key side), so you draw a big box (label with a border) for the "container"
table and a smaller box inside it for the "collection" table that's
"contained" within.

+--------------------+
| Invoice |
| |
| +--------------+ |
| | Invoice Line | |
| | | |
| +--------------+ |
+--------------------+

Note that since these diagrams might be shown to management, the label
captions might name the concepts in plain language and not exactly follow
the
table names, but it should always be obvious which tables they must be
referring to. For instance, the diagram above might be describing tables
called tblInvoice and tblInvoiceLine.

Now, if you have, say, a many-to-many relationship, that's 2 tables, each
containing items in the junction table that are also contained by records
in
the other m-m table. In this case, you draw the many-to-many table boxes
adjacent to each other, but not overlapping (don't align the corners, or
the 2
rectangles will seem to be one bisected rectangle), and draw the junction
table as a smaller rectangle overlapping the boundary between the 2 m-m
tables. It's fairly trivial to extend this to model some much more
interesting constructs.

+----------+
| Contact +----------+
| | Role |
| +--------------+ |
| | Contact/Role | |
| +--------------+ |
| | |
+----------+ |
+----------+

Of course, no terribly complex model can be completely illustrated in a
single
diagram of this form, and that's fine. You just make a diagram for each
significant concept in the model, and many tables will appear on different
diagrams in different roles. Concepts that are more easily understood
simply
by looking at the ERD, of course, don't need a diagram at all, assuming
your
ERD can be laid out reasonably well in the Relationships pane.

Other details of the scheme:
- If you need to represent constraints (enforced by schema or just
business
rules) on the number of related records such as 1-to-1 or 1-to-2, add a
label
with a light-grey border overlapping the boundary line that says "1 to 1"
or
whatever.
- If you really have to show a relationship that doesn't fit in the
hierarchical box model, draw a line from one box to the other with an
arrow
head pointing to the many-side table box. Keep these lines vertical or
horizontal, so it's easy to make and arrow head out of 2 little lines.
- You can use left and right text alignment and/or insert line breaks to
move
the label caption out of the way of other overlapping label boxes.
- If it's impossible to show a table overlapping the rectangles you need
without also intersecting another rectangle it does -not- relate to, put a
label with an X on the boundary to indicate this fact.

One question: When you transport your diagrams from one place to another,
how do you protect them from vibrations that might dislodge the magnetic
particles?

Nov 13 '05 #8

P: n/a
XMVP wrote:
One question: When you transport your diagrams from one place to another,
how do you protect them from vibrations that might dislodge the magnetic
particles?


Use a Pelican case.

--
This sig left intentionally blank
Nov 13 '05 #9

This discussion thread is closed

Replies have been disabled for this discussion.