0

I'm trying to find the right verb for database documentation. I have to write a lot of these and it is very long; so I am working for a consistent and reusable way to phrase this.

What I have now:

This tag is assigned if the field FieldName is Value.

It may look like

This tag is assigned if the field City is Chicago.

I'm struggling with the 2nd is.

Perhaps the following:

This tag is assigned if the FieldName contains Value.

That may be a little open-ended if one value is expected.

This tag is assigned if the FieldName value is Value.

What verb would you choose in this case, or how would you rework the sentence?

For context, I'm trying to document an SQL query like:

select * from locations where city = 'chicago'
user11111111111
  • 1,763
  • 1
  • 9
  • 30
Pierce Devol
  • 291
  • 1
  • 12

2 Answers2

4

Your first suggestion looks fine. It doesn't seem likely to be misconstrued. There are other similar sentences that would convey the same information in slightly different words, such as:

This tag is assigned if FieldName is Value

This tag is assigned when field FieldName is Value

This tag is assigned if field: FieldName is Value

This tag is assigned if field FieldName equals Value

To me, none of these seems any better than the others.

The important thing is that you should not use contains in place of is or equals.

Contains suggests this SQL query, which is likely to have very different results:

SELECT * FROM locations WHERE city LIKE '%chicago%'
Juhasz
  • 360
  • 1
  • 5
3

I would argue against the use of "is" to describe the relationship. There are too many usages of "is" to allow it to be interpreted with the precision that technical writing must have.

This is overly fussy, but after decades of trying to communicate technical details to non-technical audiences, I feel totally justified.

For an exact match, I would write: the value stored in "fieldName" equals exactly the string 'appropriateConstant'. I do not guarantee that no one will misinterpreted this but there is a limit to how much dumbing-down is allowed.

For a beginning substring match, I would write: the value stored in "fieldName" begins with or is exactly equal to the string 'appropriateConstant'.

For a any-place-in-the-string substring match, I would write: the value stored in "fieldName" contains somewhere in its body or is exactly equal to the string 'appropriateConstant'.

Because this is very wordy and you might have to repeat this many times, you might want to create shorthand notations such as EQ("fieldName",'appropriateConstant') or BEGINS("fieldName",'appropriateConstant').

There is a variation of Murphy's Law used by the Air Force: if it is possible to install a part the wrong way, someone, somewhere, is making that mistake right now. The variation of that law that applies here is that if it is possible to misinterpret the meaning, then someone, somewhere, will certainly do just that.

You have been warned.

JonStonecash
  • 5,267
  • 12
  • 25