 | |
Neat database diagrammatic documentation scheme
comp.databases.ms-access comp.databases.ms-access
 |
| | Thread Tools | Display Modes |
#1
 
| |||
| |||
|
Neat database diagrammatic documentation scheme -
11-30-2004
, 03:08 AM
|
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.
+----------+
Quote:
|
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.
#2
| |||
| |||
|
|
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. |
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 :-)
Quote:
|
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. |
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
#3
| |||
| |||
|
|
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. |
Quote:
|
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 :-) |
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.
Quote:
|
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 :-) |
#4
| |||
| |||
|
|
can be retrieved by the extractor without intervention. Nice. Is it sort of modelled after JavaDoc? |
Quote:
|
I find the next best thing is to just code by intention, so that the code almost reads like documentation. |
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
#5
| |||
| |||
|
|
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.
+-----------------+
Quote:
|
Invoice | +------------------+ +--------------+ Discount | | Invoice Line | | | +----------+--------------+ | | | Invoice Line / Discount | | | +----------+--------------+ | +--------------+ | +-----------------+ | |
On Tue, 30 Nov 2004 09:08:33 GMT, Steve Jorgensen <nospam (AT) nospam (DOT) nospam>
wrote:
Quote:
|
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. |
#6
| |||
| |||
|
|
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? |
#7
| |||
| |||
|
|
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. |
#8
| |||
| |||
|
|
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?
#9
| |||
| |||
|
|
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? |
--
This sig left intentionally blank
|
« Previous Thread
|
Next Thread »
| Thread Tools | |
| Display Modes | |
Linear Mode
| |
Powered by vBulletin Version 3.5.3
Copyright ©2000 - 2012, Jelsoft Enterprises Ltd.
Copyright ©2000 - 2012, Jelsoft Enterprises Ltd.