473,698 Members | 2,156 Online
Bytes | Software Development & Data Engineering Community
+ Post

Home Posts Topics Members FAQ

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 1728
> 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.*********@he uvelqop.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
documentatio n. 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.*********@he uvelqop.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.c om...
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
33935
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 capabilities, unfortunately. I'd like to know if it may be possible to add a powerful macro system to Python, while keeping its amazing syntax, and if it could be possible to add Pythonistic syntax to Lisp or Scheme, while keeping all of the...
0
1327
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 defines an URN Scheme for XML documents that works on a delegation model. As XUS (XML URN Scheme) is used exclusively for XML documents, it uses namespace URIs to identify this scheme and the delegate scheme.
9
9475
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 classes in a SQL database. The only problem is, I'm having a heck of a time trying to design the database tables in a normalized way. I have searched high and low for examples of CSS entity-relationship diagrams--to no avail. Has anyone here...
8
4393
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 a little "off", I'm not familiar with pgsql (yet). I need to be able to move the database files, as normal user-visible files, between machines. I.e. given a database on machine A, I want to be able to copy either a single file (ideally) or a...
24
3105
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 (primary key) FirstName MiddleName LastName
12
4856
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 available for reference. Thanks, Ray
0
1447
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 extensively along with the Outlining key functions to organize and navigate my code. In general, having an uncatagorized list of undifferentiated declarations in the generated HTML documentation is not all that helpful. Please have VS.Net do one of the...
12
1566
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 reasonable?
1
1282
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 am going to describe the scheme I'm using, and then I'm going to describe another scheme that may be more OO but that I have not tried. I'm hoping someone vastly smarter and more experienced than me will critique this and/or tell me a yet...
0
8603
by: Hystou | last post by:
Most computers default to English, but sometimes we require a different language, especially when relocating. Forgot to request a specific language before your computer shipped? No problem! You can effortlessly switch the default language on Windows 10 without reinstalling. I'll walk you through it. First, let's disable language synchronization. With a Microsoft account, language settings sync across devices. To prevent any complications,...
0
9157
Oralloy
by: Oralloy | last post by:
Hello folks, I am unable to find appropriate documentation on the type promotion of bit-fields when using the generalised comparison operator "<=>". The problem is that using the GNU compilers, it seems that the internal comparison operator "<=>" tries to promote arguments from unsigned to signed. This is as boiled down as I can make it. Here is my compilation command: g++-12 -std=c++20 -Wnarrowing bit_field.cpp Here is the code in...
1
8895
by: Hystou | last post by:
Overview: Windows 11 and 10 have less user interface control over operating system update behaviour than previous versions of Windows. In Windows 11 and 10, there is no way to turn off the Windows Update option using the Control Panel or Settings app; it automatically checks for updates and installs any it finds, whether you like it or not. For most users, this new feature is actually very convenient. If you want to control the update process,...
0
7725
agi2029
by: agi2029 | last post by:
Let's talk about the concept of autonomous AI software engineers and no-code agents. These AIs are designed to manage the entire lifecycle of a software development project—planning, coding, testing, and deployment—without human intervention. Imagine an AI that can take a project description, break it down, write the code, debug it, and then launch it, all on its own.... Now, this would greatly impact the work of software developers. The idea...
0
5860
by: conductexam | last post by:
I have .net C# application in which I am extracting data from word file and save it in database particularly. To store word all data as it is I am converting the whole word file firstly in HTML and then checking html paragraph one by one. At the time of converting from word file to html my equations which are in the word document file was convert into image. Globals.ThisAddIn.Application.ActiveDocument.Select();...
0
4619
by: adsilva | last post by:
A Windows Forms form does not have the event Unload, like VB6. What one acts like?
1
3046
by: 6302768590 | last post by:
Hai team i want code for transfer the data from one system to another through IP address by using C# our system has to for every 5mins then we have to update the data what the data is updated we have to send another system
2
2329
muto222
by: muto222 | last post by:
How can i add a mobile payment intergratation into php mysql website.
3
2001
bsmnconsultancy
by: bsmnconsultancy | last post by:
In today's digital era, a well-designed website is crucial for businesses looking to succeed. Whether you're a small business owner or a large corporation in Toronto, having a strong online presence can significantly impact your brand's success. BSMN Consultancy, a leader in Website Development in Toronto offers valuable insights into creating effective websites that not only look great but also perform exceptionally well. In this comprehensive...

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.