How can I consistently distinguish among tables, fields, and records in a database?
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
treein the trees table can be associated with zero or moreapplerecords in the apples table, but eachapplecomes from only onetree. Eachapplehas 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.
This post was sourced from https://writers.stackexchange.com/q/7502. It is licensed under CC BY-SA 3.0.
1 answer
Does the publication in question have relevant style guidelines? (I'm assuming not or you wouldn't be asking here.)
In your proposed solution, you are using both formatting and (initial) explicit labeling to convey information: "the trees table" rather than just "trees", for instance. This is good; it reinforces your formatting convention while facilitating scanning of the text. (It would be easy to miss that common words like "trees" are actually proper names in your database.) You may encounter sentences where this verbosity gets in your way and you're tempted to use just the formatting; that can work well for later stages of a description, like in your "but..." clause, but I recommend leading off any new discussion with the more-verbose form.
In addition, in technical writing (as distinct from other prose), it is helpful to be ruthlessly consistent in your use of technical terms, lest a reader see the absence of something as significant. In your example, you say a tree "can be associated with" one or more apples; when talking about the reverse I recommend using the "associated" language rather than the more colloquial "comes from", especially if there actually isn't any directionality to the associations. (That is, since you're talking about databases rather than graphs or pointers, I assume you mean bi-directional joins.) For an audience fluent in databases I wouldn't make this recommendation, but your audience is more general (judging from comments on the question) so give them the extra help.
This is tangential to your question but I couldn't help noticing: is the color field red/green/null, or is the value of the color field red/green/null? That is, does the field describe the column (as you said up front), or does it describe the "cell" (the value of that attribute for a particular record)? I bring this up because it's another example of the kind of precision that's really important, particularly for an audience that isn't already familiar with the domain and its terminology.
Putting all this together, I would revise your paragraph thus:
Each
treerecord in the trees table is associated with zero or moreapplerecords in the apples table, but eachappleis associated with only onetree. Eachapplehas a color field with a value of "red", "green", or NULL.
0 comment threads
0 comment threads