Technical Writing Style Guide: Part 2 – Define Your Meaning

Prerequisite knowledge: 8th grade English reading ability
Word count: 1147  Estimated read time: 3 – 4 minutes

This blog post will address three critical-to-address, pervasive grammar mistakes that I have repeatedly observed across a myriad of instructional technical writings; specifically, in definitions and explanations of technical terms. The targeted audience is anyone who teaches, writes, or explains coding-related material.

Who am I to say?

I am a photographer and journalist-turned-JavaScript Developer. I have an Master of Arts in Journalism from Napier University in Scotland, where one grammar mistake would warrant a fail for an assignment. I am hereby authorized to declare: terrible grammar is inhibiting the transfer of knowledge across the software development industry!

Over the past two years, as I zigzagged along on my own haphazard learning trajectory (thanks, Twitter, for drawing me out to so many random tech seminars), I have read plenty of educational blog posts, Stackoverflow answers, framework documentation, and complete tutorials on JavaScript, web standards, and related technologies. Despite the plentitude of online learning resources, the learning curve is still forebodingly steep for anyone aiming to learn a language, framework, or tool by Googling and self-teaching it. This is not just due to the complexity of the computer science concepts involved, but also due to incomplete, poor quality writing and documentation.

The most critical-to-address, pervasive writing mistakes in technical documentation and explanations are:

1) Vague word choice
2) Poorly-constructed definitions that lack nouns
3) Overuse of pronouns

1) Vague word choice

Words with broad, general meanings fail to set context and constrain the meaning of a definition or explanation. Examples: Data is “a thing.” This function will “do something.” Vague word choice will lead imaginative learners to ask an onslaught of questions as wide as your word choice will allow.

Include specific-enough words in your definitions and explanations, and you will save your audience the energy of asking questions which they likely strained to refine. You will save yourself the energy of answering questions that seem to come from left field. Finally, specific word choice will save learners time by trimming down the possible solution paths they will need to evaluate or analyze.

A terrific example of vague word choice is tackled by my comment on this GitHub issue. In it, I propose rewording the instructions for this online coding camp’s JSON coding challenge.

This EnvatoTuts blog post written by Cho S. Kim emphasizes the importance of setting a specific-enough context with the right words while teaching abstract concepts.

He asks, “What is a data structure?” The typical smug reply of “data with structure” does not help the imaginative learner. Believe me, that phrase can be interpreted in a plethora of ways.

Cho avoids vagueness and draws an appropriate context when he explains, “A Set isn’t a thing; a Set is the name assigned to a particular way of organizing data. What’s equally important, a Set is created using objects.” Hats off to Cho for using specific word choice to convey the appropriate context!

But there’s more; for specific word choice is not all that has been lacking…

2) Poorly-constructed definitions that lack nouns

I have read numerous attempts at definitions that only describe a term’s use cases, behaviors, context, or relationship to other terminology, but fail to articulate what the term actually is. That is because the definition lacks a noun that gives meaning to all other words in the definition.

Example from an online coding school that charges students a fee for some classes (I will omit citing names so that I may openly criticize): “Directives are how we bind behavior to the view.” Although this statement contains specific word choice, it lacks a defining noun, and therefore the statement does not constrain meaning and set context; i.e., it does not tell the audience what a directive is not; for instance, that directives are not a glittery dust that AngularJS developers blow from the palm of their hand onto their screen after having just written a controller. A helpful, lucid definition of a directive is available on AngularJS’s official documentation: “At a high level, directives are markers on a DOM element (such as an attribute, element name, comment or CSS class) that tell AngularJS’s HTML compiler ($compile) to attach a specified behavior to that DOM element (e.g. via event listeners), or even to transform the DOM element and its children.” I would argue that this definition could be further strengthened by replacing “markers” with “annotations.”

A clear, legitimate definition typically includes the main noun within the first three words of the definition. Whenever you are writing about a technical term, quote the authoritative definition found on the technology’s official documentation before elaborating on it with your own words.

Poorly-constructed definitions that lack a key noun commonly start with “is when.” Beginning this way results in nothing more than an adverbial description of the term’s context, behavior, or effects. Example: “Scope is where a function can get executed.”

Poorly-constructed definitions that start with “is how” are likewise just adverbial descriptions of the term’s means, ways, or manners. Example: “Scope is how we determine where in our code a function can get executed.” (By the way, who does “we” refer to? Please avoid pronouns that refer to undefined subjects.)

Sometimes poorly-constructed definitions skip straight to the verb. Example: “Scope refers to the visibility of variables.” Due to the lack of a noun as subject, readers only know that scope is something that refers to the visibility of variables, but what? What is scope?

The following is an example of a properly-written definition of scope: “the region of program source in which an identifier is meaningful” (Source: http://www.yourdictionary.com/scope). Illuminating! Though I am not sure what region means.

Superior to that definition is Kyle Simpson’s definition of scope: “Scope is the set of rules that determines where and how a variable (identifier) can be looked-up” (Source: You Don’t Know JS: Scope & Closures by Kyle Simpson). Scope is not a thing; scope is a set of rules. Eureka!

3) Overuse of pronouns

Be sure to accurately and succinctly name all the pertinent nouns in your definition or explanation while avoiding using pronouns such as “it” and “we” unless the pronoun unmistakably refers to one obviously distinct noun, known in grammar as the antecedent.

In Grammar, a pronoun is a word that takes the place of a noun (source: http://www.grammarbook.com/grammar/pronoun.asp). Nouns and pronouns are either subjects that perform an action or objects that receive an action. Here is an example of properly using a pronoun: “Bob deployed the application to the cloud. He tested it there.” Because there are no other reasonable possibilities, it is obvious that “he” refers to “Bob,” “it” refers to “application,” and “there” refers to “cloud.”

As defined by Merriam-Webster’s dictionary, an antecedent is a substantive word, phrase, or clause whose denotation, i.e., literal meaning, is referred to by a pronoun (source: http://www.merriam-webster.com/dictionary/antecedent).

“Bob” is the antecedent of “he,” “application” is the antecedent of “it,” and “cloud” is the antecedent of “there.”

Bearing in mind these concepts on clear pronoun usage and concise word choice, technical instructors who have slipped into the habit of stating, for example, that “we are parsing code,” would serve their audience better by rephrasing that to “the JavaScript engine is parsing code.”

If in spoken conversation you find yourself having difficulty articulating concepts about code without using pronouns such as “it” or “they,” consider using a laser pointer to clarify your meaning so that you can point it out to students as you explain “how these will get passed to it at the end of all of this.”

In conclusion

As a general courtesy to your coding colleagues, clients, mentees, and readers, remember that expressing your thoughts in complete sentences – replete with a subject and a predicate – will increase the likelihood that you will effectively convey your knowledge to your audience.

In order to facilitate better knowledge sharing across the tech industry, please avoid vague word choice, poorly-constructed definitions that lack nouns, and overuse of pronouns whenever you are writing instructions, guidance, definitions, or explanations about how to code.

Leave a Reply

Your email address will not be published. Required fields are marked *