I am describing a database for a scientific publication. The database has many tables, and each table has fields (spreadsheet columns) and records (rows).
I spend a lot of time discussing tables and relationships among tables, as well as the meanings of individual fields and records.
So here is the most descriptive "long-form" version:
The "trees" table is related to "apples" table so that each "tree" (record in the "trees" table) can have zero or more records in the apples table, but each individual apple (a record in the apples table) comes from only one tree. An apple record includes a color field, and apples can be either "red", "green", or NULL.
Here is a more realistic representation of my current draft (which requires revision for clarity):
The trees table is related to apples table and each tree may have zero or more apples, but each apple comes from only one tree. An apple's color can be "red", "green", or NULL.
I could define a convention, such as "table names in bold, fields in italics, and records in
code. This would reduce the above to:
treein the trees table can be associated with zero or more
applerecords in the apples table, but each
applecomes from only one
applehas a color field that can be either "red", "green", or NULL.
I would like to know: what can I do to provide a clear and consistent interpretation of the database.
In addition to the sentence-level suggestions, I would appreciate paragraph and section level advice - for example, how to describe a table in one or two paragraphs? How to mapping a relational database to a linear prose - currently they are organized into a logical story in order of decreasing importance of the table.