467,915 Members | 1,116 Online
Bytes | Developer Community
New Post

Home Posts Topics Members FAQ

Post your question to a community of 467,915 developers. It's quick & easy.

How do you store/manage/present the documentation for your database?

I have a database documentation question, but I am not even sure how
to phrase it properly so I don't know where to start looking for
answers.

We are developing a database that is based on several different data
standards and schema. I'm finding it confusing to keep it all
straight. What's this field for? Which standards document is it based
on? What are the permitted values? Which business rule governs it?

In theory, we do have all that information in our hands -- but it's
not easily available; it is scattered among lots of separate
documents, in dead text pages, in varying formats. I wish I could have
all of that information built into our application, where it's
actually needed.

(In my experience, the business rules and permitted values may be
built into the hidden code and the field properties and the form
controls of a database, but doing so doesn't make this information
easily accessible for review. I have spent days poking around other
people's databases, examining the properties of each and every little
object, trying to figure out how things worked. Without good
documentation, this is maddening.)

Is there a preferred, or recommended, way to store and manage all this
information in an organized fashion? One approach I have considered is
to create a "tblFieldMetadata" table where each record represents one
of the actual fields in the database, with fields like
TableAndFieldName, StandardsDocument, Schema, FieldDescription, and
BusinessRule. I have even considered having a one-to-many link to a
"tblFieldMetadataPermittedValues" table that stores all the defined
permitted values for all the fields, with additional fields for
commentary. Is this a bad idea?

And is there a preferred, or recommended, way to present all this
information from within the application, so that a user can
conveniently call it up at the point when it's needed without having
to invoke a separate help file or user manual? I imagine this is
probably dependent on the exact products and technology being used.
Are there instances that stand out in your experience as being really
great examples of good presentation of this kind of information?

Thanks in advance for any comments.

Feb 27 '07 #1
  • viewed: 2029
Share:
1 Reply
Good question, Eric. I'm not sure there is a one-size-fits-all answer to
this. It depends of you are developing for yourself, for the organization
are employed by, for paying clients, on your own, or as part of a
development team, not to mention the level of complexity and critical nature
of the business rules.

Perhaps we can ignore the case where you are developing for yourself, as
these projects are generally ill-defined. If you are developing for a
client, the first stage must be a decent specification - typically a word
document that defines what information will be stored about what entities,
what reports are required, security, maintenance, and so on. While this
document is written in a non-technical manner, it must cover all business
rules. The project I've just completed was based on a spec I wrote 2 years
ago for a not-for-profit group that took that long to get the funding
together. But the document made it clear which fields were required, what
business rules apply, and so on. So this document covered everything that
was needed to make the design choices and develop the db. (It was around 10k
words of terse text.)

Next comes the design of the actual data structure. Some of these decisions
are not explicitly stated in the spec, but can be deduced - things like
making foreign key fields required, setting Allow Zero Length to No, and
what to use as the Description of each field (which will be copied to the
Status Bar Text of the controls), and naming conventions. If you are working
as a team, you probably have most of these things covered. If you work
alone, you have probably evolved your own style. Either way, I'm beginning
to think that it might be possible to automate the development of about 60%
of the interface, just based on a really consistent and well-designed data
structure and consistent development rules/style.

Once the data structure is in place, it is possible to use tools to document
it. The one I use primarily adds field information to the Relationships
report:
http://allenbrowne.com/AppRelReport.html
If you want a text-based one (beyond the built-in documenter), Jeff Conrad
has one here:
http://home.bendbroadband.com/conrad.../csdtools.html
Personally I don't see a point in storing this info in a table when it can
be generated so easily as needed.

The information is now spread across 2 documents: the original specification
the explains in layman's terms what should be, and the technical document
(or diagram in my case) that explains what is. While no 2 developers will
end up with exactly the same structure for the same project, you can test
whether the actual implementation meets all the requirements of the
specification or not.

Once the database has been developed (based on the structure developed from
the spec), you need to write the user manual. Again this is a non-technical
document, but it will cover what is expected/permitted at each screen, so it
effectively explains the business rules as well as the structure. Presumably
you have tested and debugged each stage as you went, so you now have the
chance to create some test data and do the final testing/debugging of the
whole integrated app as you write the documentation. That is, you write that
it does xyz, and actually test that it does xyz as you go, so the
application you deliver matches exactly what the documentation says. In this
way, the user manual becomes a functional definition of the database, as
distinct from the structural documentation the tools above generate.

A development team will undoubtedly have its own rules beyond what we just
described. But hopefully that will help with fitting all the crucial pieces
together without spending time on anything that is not absolutely essential.

--
Allen Browne - Microsoft MVP. Perth, Western Australia
Tips for Access users - http://allenbrowne.com/tips.html
Reply to group, rather than allenbrowne at mvps dot org.

"Eric Sadoyama" <er***********@gmail.comwrote in message
news:11**********************@t69g2000cwt.googlegr oups.com...
>I have a database documentation question, but I am not even sure how
to phrase it properly so I don't know where to start looking for
answers.

We are developing a database that is based on several different data
standards and schema. I'm finding it confusing to keep it all
straight. What's this field for? Which standards document is it based
on? What are the permitted values? Which business rule governs it?

In theory, we do have all that information in our hands -- but it's
not easily available; it is scattered among lots of separate
documents, in dead text pages, in varying formats. I wish I could have
all of that information built into our application, where it's
actually needed.

(In my experience, the business rules and permitted values may be
built into the hidden code and the field properties and the form
controls of a database, but doing so doesn't make this information
easily accessible for review. I have spent days poking around other
people's databases, examining the properties of each and every little
object, trying to figure out how things worked. Without good
documentation, this is maddening.)

Is there a preferred, or recommended, way to store and manage all this
information in an organized fashion? One approach I have considered is
to create a "tblFieldMetadata" table where each record represents one
of the actual fields in the database, with fields like
TableAndFieldName, StandardsDocument, Schema, FieldDescription, and
BusinessRule. I have even considered having a one-to-many link to a
"tblFieldMetadataPermittedValues" table that stores all the defined
permitted values for all the fields, with additional fields for
commentary. Is this a bad idea?

And is there a preferred, or recommended, way to present all this
information from within the application, so that a user can
conveniently call it up at the point when it's needed without having
to invoke a separate help file or user manual? I imagine this is
probably dependent on the exact products and technology being used.
Are there instances that stand out in your experience as being really
great examples of good presentation of this kind of information?

Thanks in advance for any comments.
Feb 28 '07 #2

This discussion thread is closed

Replies have been disabled for this discussion.

Similar topics

4 posts views Thread by Christopher Brandsdal | last post: by
1 post views Thread by James T. | last post: by
3 posts views Thread by noridotjabi | last post: by
4 posts views Thread by Ranginald | last post: by
8 posts views Thread by romayankin | last post: by
By using this site, you agree to our Privacy Policy and Terms of Use.