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.

Leave a Reply

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