Is domain-specific meaning acceptable/advisable when used in a document directed outside the domain?

Question

Here's the problem. Many common terms in the programmer's lexicon--i.e., used in information communication and in published texts--are identical to everyday words; others are slight 'distortions' of everyday words (so that if you saw them but weren't a programmer, you'd swear they were misspelled or used incorrectly). It's this latter category that's the focus of my question. Some examples:

• persist (a verb, e.g., you 'persist' data by writing it to a RDBMS);

• instantiate (invoke a function which creates an object bound to a variable);

• deprecate (e.g., replace an old feature with a new one, and leave the old feature in the language temporarily to preserve backwards-compatability)

A colleague and i recently finished writing a book largely directed to programming though the intended audience is mostly (but not exclusively) non-programmers (for instance, marketing managers and other people who often wear ties).

Our editor does not like words like these in the text.

In particular, she feels strongly that terms like the ones i just recited should be replaced with a short descriptive phrase that's more consonant with the conventional business lexicon.

We argue that fidelity to the language of the relevant community is what's most important--i.e., most of the concept we are trying to explain in the book are embodied in these specialist terms, and if the reader doesn't learn those terms then the book will have very little if any practical significance for them because they won't be able to communicate with the specialists who are required to implement the systems described in the book. In addition, we contend that by providing a glossary or endnotes, the reader can easily absorb the unfamiliar terminology.

Arguing from the details though doesn't appear ever likely to persuade either 'side,' and so I would very much appreciate the higher-level views from this community.

Answer 1

This is interesting and something I always thought about when reading programming materials in German since this problem is solved: if it is an English word like instantiate then it is a tech word and there is another German word for that same concept even if is it basically the Latin equivalent, e.g. instanziieren. So you know if the English word is being used, it has the tech meaning, and if the German word is being used, it has the conventional meaning.

So I see your conundrum when writing an IT book in English.

Perhaps you and the editor could just agree on a special font/color for these English words that have special IT meanings, so you would have sentences like this:

The managers persisted in reminding us that the data had to be persisted in both SQL Server and MySQL.

Answer 2

To me it's obvious that you should do what the editor suggests. I can't tell you how exasperating it is to read text where the authors insist on introducing jargon words for no apparent reason, just because that is the way that the experts talk. It slows down my pace of reading and thus is highly irritating, and I usually feel like the author is just wasting my time in order to show how clever he is by using these words. Glossaries and endnotes are just really annoying. Does your message to the "suits" really consists of teaching them this jargon? If not, remove them as your editor suggests, or put the jargon into the endnotes/footnotes/a special section.

Answer 3

It depends on what the domain is. If you were writing a popular science book on physics you would of course use words and phrases like black hole, electron, quark, and quantum tunnelling. That is because there are no alternatives. An explanation of what a black hole is should be included, either in a glossary or on the first occurrence of the phrase (or, ideally, both), but you can't use that explanation in place of the phrase throughout, because if you did the book would be three times as thick and completely unreadable. Physics jargon is useful and necessary, because it's describing genuinely complicated things.

In some of the liberal arts, by contrast, I rather suspect the jargon is made up to dress fairly simple concepts in fancy language to make it seem more important. I imagine it would be quite easy to write a book on art history without including a single jargon word anywhere.

So that's one good reason to use jargon: used correctly, for the right purpose, it simplifies the text. Does that apply to programming? You could certainly drop the verb-meaning of persist, and perhaps all the examples you give, without making your text more complicated.

The other good reason to use jargon is, as you say in your question, to familiarise the reader with that jargon. To that end, I would suggest using both terms together the first few times, and later in the book dropping the explanation.

This feature has been depricated (it has been replaced but is preserved for the sake of compatibility; it may be dropped in later versions of the specification).

Later

This has now been depricated (it's on the way out).

Later

This function is no longer recommended for use, and will probably shortly cease to exist, as it was officially depricated in version 2.4.

(Note that the word depricated is no longer marked as a technical term here. Nor is it defined, as such, but it's easy to work out the meaning from the context.)

And finally

Version 3 of the standard depricated a large number of functions.

(No explanation at all.)

This strategy does, of course, reply on the assumption that your readers will start at the beginning and read through to the end, which is not the way all textbooks or reference manuals are supposed to be read. If you're writing a book with independent chapters which may be read in any order, you'll have to go with no jargon or with explanations throughout.

Another option is to use a glossary and to also include extracts from the glossary as blurb text in the margin alongside the use of the words. This means there's a definition to hand wherever a technical word is used, and also a handy list in the back of the book.