473,325 Members | 2,342 Online
Bytes | Software Development & Data Engineering Community
Post Job

Home Posts Topics Members FAQ

Join Bytes to post your question to a community of 473,325 software developers and data experts.

Neat database diagrammatic documentation scheme

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
8 1710
> 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
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
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
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
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
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

"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
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 thread has been closed and replies have been disabled. Please start a new discussion.

Similar topics

699
by: mike420 | last post by:
I think everyone who used Python will agree that its syntax is the best thing going for it. It is very readable and easy for everyone to learn. But, Python does not a have very good macro...
0
by: Philippe Poulard | last post by:
I don't know if anybody already designed an URN scheme for XML; here is a proposal: I call it the "XML URN Scheme", or XUS. ========= URNs are logical names used to identify resources. XUS...
9
by: Big Slim | last post by:
I'm working on a web application that makes heavy use of CSS, but I would like users to have a degree of control over some of the classes and attributes. To accomplish this, I want to store my CSS...
8
by: Gail Zacharias | last post by:
I am investigating the possibility of using pgsql as the database in an application. I have some unusual requirements that I'd like to ask you all about. I apologize in advance if my terminology is...
24
by: flkeyman | last post by:
Work in legal office. Trying to create solid designed database structure. This is list of tables w/fields and primary keys. Any comments/advice greatly appreciated. tbl-Defendants CaseNumber...
12
by: Ray | last post by:
I just completed a database and would like to prepare the documentation for it. As I have no experience to do so, can someone advise me the essential elements for the documentation and any example...
0
by: MS | last post by:
Is the schema used to validate XML Documentation Comments available to be changed by a VS.Net user? I suspect the this question is no so have a couple of requests: 1.) I use #region...
12
by: Ben | last post by:
If I have have the table: create table foo ( a int references bar(id), b int references baz(id) ) .... how do I make sure one and only one of the columns a and b are non-null? Is it even...
1
by: | last post by:
Hi. This is a a semi-newbie question about how to store arbitrary information about my apps such that I can code quickly, mimizing complexity and the number of things I have to hold in my brain. I...
0
isladogs
by: isladogs | last post by:
The next Access Europe meeting will be on Wednesday 6 Mar 2024 starting at 18:00 UK time (6PM UTC) and finishing at about 19:15 (7.15PM). In this month's session, we are pleased to welcome back...
1
isladogs
by: isladogs | last post by:
The next Access Europe meeting will be on Wednesday 6 Mar 2024 starting at 18:00 UK time (6PM UTC) and finishing at about 19:15 (7.15PM). In this month's session, we are pleased to welcome back...
0
by: Vimpel783 | last post by:
Hello! Guys, I found this code on the Internet, but I need to modify it a little. It works well, the problem is this: Data is sent from only one cell, in this case B5, but it is necessary that data...
0
by: ArrayDB | last post by:
The error message I've encountered is; ERROR:root:Error generating model response: exception: access violation writing 0x0000000000005140, which seems to be indicative of an access violation...
1
by: Defcon1945 | last post by:
I'm trying to learn Python using Pycharm but import shutil doesn't work
1
by: Shællîpôpï 09 | last post by:
If u are using a keypad phone, how do u turn on JavaScript, to access features like WhatsApp, Facebook, Instagram....
0
by: af34tf | last post by:
Hi Guys, I have a domain whose name is BytesLimited.com, and I want to sell it. Does anyone know about platforms that allow me to list my domain in auction for free. Thank you
0
by: Faith0G | last post by:
I am starting a new it consulting business and it's been a while since I setup a new website. Is wordpress still the best web based software for hosting a 5 page website? The webpages will be...
0
isladogs
by: isladogs | last post by:
The next Access Europe User Group meeting will be on Wednesday 3 Apr 2024 starting at 18:00 UK time (6PM UTC+1) and finishing by 19:30 (7.30PM). In this session, we are pleased to welcome former...

By using Bytes.com and it's services, you agree to our Privacy Policy and Terms of Use.

To disable or enable advertisements and analytics tracking please visit the manage ads & tracking page.