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.

Leave a Reply

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