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.

  • more consonant? – delete Aug 14 '10 at 8:09
  • 1
    @Ex-user: bbzzxxjkjlmjkzjxkkjfhgj – Claudiu Oct 22 '10 at 22:36
  • "consonant" - Latin for "in tune"? Con can mean with, as much as be an enforcer of the rest of the word. So "self sounding" could well be translated as "swinging, sounding along with". ;) – malach Oct 23 '10 at 10:06

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.

| improve this answer | |
  • 1
    Using a special font and colour for certain special words sounds like a nightmare for readability. – delete Aug 14 '10 at 8:19
  • 3
    It doesn't have to be eye-straining, I just mean like the word File on this page of this C# Head First O'Reilly book: is.gd/ehhbB The editor mentioned in the question obviously wants these words to stand out showing that they have a different meaning than their conventional equivalents. – Edward Tanguay Aug 14 '10 at 10:26
  • +1, just bold the words when they are used first, maybe have a glossary? but avoid introducing like 10 terms quickly and then using them in every sentence as tha twould be overwhelming – Claudiu Oct 22 '10 at 22:37
  • A point about “instantiieren” in German: one of the first things we learned in OOP class at University was that this word (and its “more correct” cousin “instanzieren”, note one less “i”) is an abomination and doesn’t exist. Prescriptionism aside, it’s an ugly word and alternatives exist, e.g. “[ein Objekt] erstellen”. – Konrad Rudolph Oct 24 '10 at 20:01

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.

| improve this answer | |

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).


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


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.

| improve this answer | |

The first two chapters of the venerable "Jargon File" has some useful things to say about programmers as a linguistic community.

…Among hackers, though, slang has a subtler aspect, paralleled perhaps in the slang of jazz musicians and some kinds of fine artists but hard to detect in most technical or scientific cultures; parts of it are code for shared states of consciousness. There is a whole range of altered states and problem-solving mental stances basic to high-level hacking which don't fit into conventional linguistic reality any better than a Coltrane solo or one of Maurits Escher's surreal trompe l'oeil compositions (Escher is a favorite of hackers), and hacker slang encodes these subtleties in many unobvious ways. As a simple example, take the distinction between a kluge and an elegant solution, and the differing connotations attached to each. The distinction is not only of engineering significance; it reaches right back into the nature of the generative processes in program design and asserts something important about two different kinds of relationship between the hacker and the hack. Hacker slang is unusually rich in implications of this kind, of overtones and undertones that illuminate the hackish psyche. …

So in a very real sense, the jargon used has been selected for its precision. The verbs listed: persist, instantiate, and deprecate in fact do have more precise meanings than for example, store, create, and there-is-no-synonym-I-can-think-of.

If pressing this with the editor, I'd make an argument by analogy to medical terminology which is also chosen for its precision. If I am trying to communicate about some trouble with the plantar fascia no other term will suffice. Sure, upon introduction of the term, you can explain it to the gentle reader, but when that reader tries to be understood and talks about "the connective tissue between the heel and toes on the bottom side of the foot", those skilled in the art may find the non-jargon form imprecise and even hard to understand.

You might also substitute biological nomenclature where Microtus pennsylvanicus and M. ochrogaster are nearly indistinguishable unless you look at the cusps on one of their molar teeth (for a good time, try doing a dental exam on a vole), but to one skilled in the field, they are wholly different animals.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.