Technical Writing Style Guide: Part 1 – Respect Your Audience

Prerequisite knowledge: 8th grade English reading ability
Word count: 522  Estimated read time: 1-2 minutes

Everyone deserves respect
You are an experienced software engineer or tech guru of some sort, and now you feel a sincere desire to share your knowledge with newer developers who need your guidance. This is a praiseworthy intention, but be mindful in how you take action, remembering the old English proverb “The road to hell was paved with good intentions.”

Two excellent premises to bear in mind while you write are to maintain a tone of respect for your audience’s knowledge level and respect your audience’s time.

Maintain a tone of respect

Respect your audience’s knowledge level by syncing with it
List prerequisite knowledge at the start of your article or post so that the readers can gauge whether they have the knowledge necessary to make sense of your lesson.  At the top of your article, explicitly state the general concepts or terms with which the readers should already be familiar.  If omitted, you risk either frustrating readers by taking them part way to understanding only to skip defining key terms; or, you risk patronizing readers by over-elaborating; either way, your tone may come across as presumptive, myopic, or arrogant.

Avoid being condescending and discouraging to your audience members who are newer to coding by avoiding the word “simple” when describing the solution.

Avoid being condescending and discouraging to your audience members who are newer to coding by avoiding the word “simple” when describing the solution. Remember that if it were simple, they would not be seeking guidance from you, nor would there be a burgeoning cottage industry on how to pass a coding interview. So, be respectful, because what comes around goes around. No one, not even you, knows everything.

Respect your audience’s time

Word count and estimation of the article’s read time
Busy readers often wonder, “Do I have the time to read this?” yet writers tend to omit an honest disclosure of how many minutes their wisdom-sharing words will likely devour. It is best to not draw in not-yet-hooked readers who only have n minutes to find an answer. Instead, summarize the selling points up front, along side an honest disclosure of your article’s duration, then offer an easy way for readers to bookmark the article for later: a call to action button! Bookmark me!

One subtle and popular way to hint at a longer read time is by stating something like “Grab some coffee and settle in.” This qualitative approach is easy, whereas quantifying an actual time range can get complicated due to your audience’s wide variety of reading speeds and comprehension levels. Just remember when estimating your article’s time range that technical writing is dense and typically requires readers to slow their natural reading speed in order to maintain comprehension. According to the results of the Staples-sponsored speed reading test, the average adult reads 300 words per minute; the average college student reads 450, and the average high level executive reads 575. Anyone can find out their reading speed by taking the test at the link above.

In conclusion
Be courteous and respectful of your audience’s knowledge level by including some prerequisite terms and by not talking down to them or speaking over their heads. Be respectful of your audience’s time by displaying a word count and/or estimated reading time at the beginning of your post or article.

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.

Technical Writing Style Guide: Part 3 – Setting Expectations as You Instruct

Prerequisite knowledge: none
Word count: 212  Estimated read time: 1 minute

Attention technology teachers in the blogosphere and authors of technical documentation! Here is the third post of my three part style guide on technical writing. Set expectations near the beginning of anything you write that seeks to instruct, inform, or explain code. Is your article a step-by-step, follow-along guide? If so, is it safe for readers to assume that they can practice running the example code in the order in which it appears? Answer that briefly in the beginning. Like order of operations, order of instructions matter.

Be mindful not to misdirect readers by prefacing inserted code with language such as “This is what you could do” only to follow it with “but do not actually do that.”

Be mindful not to misdirect readers by prefacing inserted code with language such as “This is what you could do” only to follow it with “but do not actually do that.” Such introductory language leads your readers to believe that the following code is a solution that works. So they often take the time to copy and paste sample code into their text editor and test it out; but, as soon as they realize something is amiss in their console, they become confused and may waste a pitiful amount of time and effort scrutinizing where they have made a mistake.

Avoid frustrating your readers by stating in front of code snippets whether the following code is meant to compile and/or run, and is worth practicing and memorizing. If it is not, give fair warning so that your reader does not waste 10 or 20 …or even 60 minutes studying its every nook and cranny, troubleshooting it in painstaking detail, and accidentally burning it deep into their memory through repeated re-reading, only to learn later down the page that the code was never meant to work.