Post History

Source: https://writers.stackexchange.com/q/7502
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

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:

> Each `tree` in the **trees** table can be associated with zero or more `apple` records in the **apples** table, but each `apple` comes from only one `tree`. Each `apple` has 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.

Original score: 5