Technical writing is the art of synthesizing complex information into palatable, bite-sized chunks. The goal of which is to help your readers understand, identify, and implement certain behaviors in order to accomplish a goal or a task.

Technical writing is an essential part of information technology, and other industries as well. Technical writing is an amazingly helpful mode of communication used to clarify and organize many complex subjects. 

Your favorite recipe for eggs benedict, or the user's manual for how to operate equipment, are both examples of subjects that utilize the principles of technical writing. 

Google has been kind enough to create a free technical writing course split into two sections. I've completed both sections and will list some of my key take-aways below.

1. Define New or Unfamiliar Terms

The goal of technical writing is to teach your reader how to do something. Therefore, it should be expected that you will be introducing new, or unfamiliar terminology to them. Be sure to take this opportunity to highlight these terms, here's how:

1. If the term already exists, provide an internal or external hyperlink to a good existing explanation.
2. If the term is being introduced, define the term for your readers.

If your document uses many technical terms, create a glossary to help your readers.

2. Use Active Voice Whenever Possible

Active and Passive Voices are communication styles that deal with the syntax structure of a sentence. Sentences are comprised of subjects, objects, and verbs. Sentences using Active Voice are structured so that the actor acts on a target. Sentences utilizing Passive Voice will do the opposite. Consider the following sentences.

• The quarterback throws the football.
• The football is thrown by the quarterback.

In the example above, the first sentence follows the following formula:

• Active Voice sentence = actor + verb + target

The second sentence uses the following formula:

• Passive Voice sentence = target + verb + actor

Active Voice is a powerful and direct alternative to Passive Voice which can make sentences unnecessarily long and confuse readers. Active Voice identifies who is doing what to whom and as a result, makes sentences shorter and more precise.

3. Use Short Sentences

For clarity in your writing, focus each sentence on a single idea. Longer sentences can be harder to grasp, confusing, and overwhelming for your readers. If you find that your document has many long sentences, consider converting those long sentences into lists instead.

4. Convert Long Sentences to Lists

Lists are essential in technical writing and can transform chaotic text into orderly information. The most commonly used lists by technical writers include:

• bulleted
• numbered
• embedded

Bulletedunordered items, where rearranging the order of those items will not change the meaning of the list. Numbered lists are for ordered items, where rearranging the order of the items will change the overall meaning of the list. Embedded lists are used within sentences, and should generally be transformed into bulleted and numbered lists when possible.

lists are for

Bulleted lists are a useful way to create a list that stands out from the text without implying a certain chronology or ordering of the items. An example would be a list of nearby restaurants or the items needed for a recipe. Numbered lists are a way to highlight information that must be performed in a chronological sequence to be effective. An example of a numbered list would be the steps in a recipe or the steps to reboot a server.

Additionally, there are a couple of other things to keep in mind when creating your lists, they include:

• Keeping the list items parallel in:
  • grammar
  • capitalization
  • punctuation
  • active/passive voice
  • logical category

For example, keep the use of complete sentences or fragments for your list items, consistent. If a period is used for one item, be sure to use a period for all items. Additionally, only use capitalization and periods for list items that are sentences, not fragments. As a rule, start numbered lists with an imperative verb, which are commands like download, configure, or start.

5. Know your Audience

Understanding your audience is an essential step for excellent technical writing. To accomplish this task, be sure to:

• Define your audience and understand their roles.
  • Is your audience software engineers? Are they clients? Are they internal employees or an external web design agency?
  • Understanding the role of your audience members allows you to make assumptions regarding how knowledgeable they would be on a given subject.
• Define your audience's proximity to the knowledge.
  • People within the same role category will generally share certain base skills and knowledge.
  • Your audience may know about a closely related subject but may have no knowledge of the subject matter you are explaining. They may understand the general rules of an API, but may have no working knowledge of how your API works for example. 
  • Be sure you understand whether they understand the basics, need a course refresher, or need prerequisite materials to help them better understand your documentation.
• Determine what your audience needs to learn.
  • After reading the documentation, what are the goals or tasks that your audience needs to perform?
  • Consider if your audience needs to learn materials in a particular order to effectively complete tasks.

6. State the Scope of your Document

A good technical document lists at the very beginning, its scope, which speaks to the breadth and complexity of the central concern of your document. 

A great technical document lists the non-scope as well, which are the topics not covered, that your target audience might reasonably expect your document to dive into. 

Scope and non-scope statements benefit the reader and also the writer. They allow both groups to focus on the key points of a subject matter to accomplish a predetermined goal.

Scope and non-scope statements also highlight any pre-required knowledge or experience requirements. This allows readers to accurately gauge if they are the target audience for a particular document.

7. Organize your Document for your Audience

Organization is essential to creating a well crafted technical document. When organizing your document, be sure to keep the following in mind:

• Define the scope and non-scope of your document.
• Create an outline and draft the introduction.
• Summarize the key points at the start and within the first paragraph of your document.
• Provide an overview of the topic at hand, as well as instructions for implementation, and information from deeper analysis.
  • Overviews often utilize the method of compare and contrast to provide familiar context to readers.
  • Overviews provide links to articles that provide additional introductory information.
  • Overviews describe optimal configurations of a process.
  • Implementation information includes how-to instructions, as well as tips, tricks, and common mistakes.
  • Deeper analysis will often cover or link to edge use cases and mention known unknowns about the subject matter to your audience.
• Explain to your audience the benefits of completing a task, before you ask them to complete it.
• Limit each step to one concept.
• Structure your outline to introduce information when it is most relevant to your reader.
• Explain the concept and then demonstrate how your reader can apply it.

8. Add Navigation

Last but not least, when creating technical documentation, be sure to add some sort of navigation to your document. This helps your audience:

• Quickly determine the scope of the document.
• Quickly determine if they are in the right place.
• Determine an effective time management strategy to get through the documentation.
• Determine where they are in the document.
• Follow a clear logical development of the subject.
• Find links to related sources or more in-depth information.
• Find links on what to learn next.

Technical writing can seem intimidating and intense, but it is actually a great way to clearly and concisely explain something incredibly complicated. It allows for a methodical, but flexible way to share information with your target audience.

So the next time you feel pressure or anxiety because you have an extraordinary complex topic that needs to be distilled for your captive audience—relax, breathe, and follow Googles tips for technical writing—you'll be glad that you did!