technical-writing.md

Technical Writing

Prerequisites

Here are links to lessons that should be completed before this lesson:

Reading & Writing Documentation

Motivation

• Being a technical writer allows you to be a first user of the application. If you like the experience of using something brand new and playing around with it, failing and improving it, you would love technical writing.

Objectives

Participants will be able to:

• Learn excellent writing skills to be able to explain technical information clearly.
• Take complex,technical information and simplify it for colleagues and consumers who have nontechnical backgrounds.
• Think about a procedure or product in the way a person without technical experience would think about it.

Specific Things to Learn

• Determine the needs of users of technical documentation.
• Ability to interact with SMEs (Subject Matter Experts).
• Standardize content across platforms and media.

Materials and Lessons

Technical writers, also called technical communicators, prepare instruction manuals, how-to guide journal articles and other supporting documents to communicate complex and technical information more easily. They also develop, gather, and disseminate technical information through an organization's communications channels.

Common Mistakes / Misconceptions

Here are some of the common mistakes Technical Writers do-

• Messy Structure : Many technical documents confuse readers and fail to achieve their aims because they were not planned properly to begin with.
• Poor punctuation : All writers have a passing knowledge of the main set of punctuation marks. Very few, however, outside of professional authors and editors, have a thorough grasp of how each one works.
• Too much abstraction : People writing in a formal or semi-formal context often go overboard in an effort to make their prose sound proper and elevated.

A few misconceptions regarding Technical Writing are as follows-

• Technical writers simply write a user manual. It is called by various fancy names for different products
• Technical documentation is an insignificant part of product development.
• It is enough to document key features of the product. Small things, the users can figure out themselves.

Independent Practice

Here are few practical and independent ways to independently learn the skill of Technical Writing

• Edit someone else's work.
• Write a style guide.
• Read other's technical writing attentively.

Challenge

• Write your own blogs.
• Write publications for different organizations and authors.

Check for Understanding

• Technical Writer Aptitude Test

Supplemental Materials

• Technical Writer with Sarah R

The following supplemental materials can help the students to go deeper into the topic. The links were selected by a Technical Writer at Indeed.

• Technical Writing in 20 minutes Part 1 Part 2

  Introductory lesson to technical writing by cherryleaf team. The lesson covers the steps to create a technical document. It provides a real example of technical writing (how to use an old film camera)

• TWFred lecturing on the basics of writing a technical topic - Fred Williams' youtube channel. He's the founder of Williams Technical and in some of his videos he talks about writing software documentation.

• Online Technical Writing: process discussions

  A step by step explanation about what process discussion is and how to write this kind of prose.

• Examples of API documentation

  Five examples of great and popular API Documentation (Stripe, Twilio, Dropbox, GitHub, Twitter)

• How to write a useful scenario walkthrough

  Useful post for people who are technically capable but unfamiliar with technical writing. A complete scenario example is provided.

• Types of technical documentation

  A quick overview of different types of technical documentation.

• Indeed Engineering Blog

• Indeed Engineering Blog on Medium

• The evolving language of data science

  An interesting post published on Medium by Indeed Engineering about the evolution of language in data science.