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.

Women in Transportation Newsletter – Fall 2013

As Co-Chair of the Communications and Newsletter committees for WTS-DC, I redesigned the newsletter and converted the fall edition to Flash format to enhance interactivity with features such as digital page turns and videos. This issue also contains my photography and articles written or edited by me.

WTS-DC Fall CoverCover of WTS-DC Newsletter Fall 2013/Photo by Lindsay Brown

Get Adobe Flash player

Women in Transportation Newsletter – Summer 2013

As Co-Chair of the Communications and Newsletter committees for WTS-DC, I redesigned the newsletter and converted the summer edition to Flash format to enhance interactivity with features such as digital page turns and videos. This issue also contains my photography as well as articles written by me.

WTS-DC Summer CoverCover of WTS-DC Newsletter June 2013/Photo by Lindsay Brown

Get Adobe Flash player

Traffic Control Device Crash Testing

Sound work for AASHTO by LindsayBrown81

This podcast provides a summary of how impact testing is conducted on traffic control products, specifically delineators and drums. It outlines how product performance is measured and reported.

To learn more about the testing protocol and data usage for the Temporary Traffic Control Device technical committee at the American Association of State Highway and Transportation Officials (AASHTO), click here. Testing results are posted in DataMine, a central repository of data for the National Transportation Product Evaluation Program (NTPEP).

The Benefits of NTPEP

AASHTO’s National Transportation Product Evaluation Program is a public-private partnership that prevents duplication of efforts among the 52 State Departments of Transportation. This audio-enhanced, animated slideshow outlines the benefits states receive by participating in this rapidly growing technical service program.

PowerPoint – 4 minutes 30 seconds

Benefits of NTPEP title pg

Click on the image above to download the file to your computer, then press F5 to play. You may pause it at any point and click on any of the hyperlinks in it. Playing will resume where you left off.


Solid-Not Slavish Relationship – Promo

produced by Lindsay Brown

Promo for the Solid-Not Slavish Relationship by LindsayBrown81

“The Solid-Not Slavish Relationship: Britain’s Media Coverage of America from September 2009 to July 2010” was produced by Lindsay Brown in part fulfillment of a Masters level dissertation for Edinburgh Napier University’s graduate program in Journalism.

Barack Obama and David Cameron renamed the relationship the “Essential Relationship” in May 2011. The original phrase the “Special Relationship” was coined shortly after World World II when Winston Churchill and Franklin Roosevelt shared a close working relationship that ebbed and flowed throughout their tenures in power.

Barney Frank’s Financial Legacy: the Dodd-Frank Act

by Lindsay Brown

Nearing the end of his 32nd year in Congress, Barney Frank, 71, announced today that he will not run for a 17th term as a Representative for the state of Massachusettes. Along with championing gay rights, Frank also spearheaded the writing of a new financial reform act which is aiming to better safeguard American people from predatory lending and unfair Wall Street greed.

Barney Frank Text BoxIn response to the financial crisis which began in September of 2008, Rep.Frank introduced the legislation along with former Senator Chris Dodd, of Connecticut. The Dodd-Frank Wall Street Reform and Consumer Protection Act, also known as the Financial Reform Bill, was passed in June of 2010 and signed into law by President Obama the next month.

However, implementing the new financial reform bill is proving to be a complicated process. Traditional economic terms, as well as new terms, have yet to be defined by the appropriate government agencies.

For example, Title VII of the Dodd-Frank Act is called the Wall Street Transparency and Accountability Act. It repeals prior laws which allowed derivative traders to be exempt from government regulation for certain security-based “swaps,” transactions that include a derivative born from nine or fewer securities. These transactions played a major role in causing many banks to fail.

The Commodity Futures Trading Commission and the Securities and Exchange Commission, along with the Federal Reserve, are still in the process of defining swap related terms that appear in Title VII, as well as terms found in the Commodity Exchange Act of 1936 and the Securities Exchange Act of 1934.

After Frank leaves, the next Chair of the House Financial Services Committee will continue to work with government agencies as they refine the details of the bill. Meanwhile, Barney Frank will remain engaged in public advocacy and may even return to his pursuit of a PhD in Government from Harvard.