2697 Words | Reading Time: 15 Minutes
What are some quick technical writing tips you can learn to give your writing some extra pop, precision, and clarity? To write well for the IT industry, you need to bridge the gap between the IT development team, product owner, and end user. But how do you keep communication as clear as possible for all three groups?
It’s challenging to switch back and forth between highly technical language and everyday language. One way to keep your writing crisp and crystal clear is to follow five technical writing tips.
But before we dive into them, let’s first clarify what technical writing is, and the writing background that will give you the advantage as a technical writer.
Contents
- What is technical writing?
- What kind of technical writing can you do in the IT industry?
- 5 tips to give you the advantage as a technical writer in IT
What Is Technical Writing?
This might surprise you. You don’t need to be a subject matter expert, with a degree in computer science to write for IT. It helps to understand programming language, but programming basics is something you can learn while you build up your writing portfolio.
Let’s begin with The Society of Technical Communication’s definition of what technical writing is:
Technical communication is a broad field and includes any form of communication that exhibits one or more of the following characteristics:
- Communicating about technical or specialized topics, such as computer applications, medical procedures, or environmental regulations.
- Communicating by using technology, such as web pages, help files, or social media sites.
- Providing instructions about how to do something, regardless of how technical the task is or even if technology is used to create or distribute that communication.
Communicating and providing instruction are important in technical communication. You might remember a time when you were learning a new computer program or platform and reading the explanation confused you even more.
When you’re writing a technical piece, you want to create a clear path for the reader to follow, especially when writing instructions.
It could be disastrous if, for example, the instructions for a financial program used by a bank and its customers were difficult to understand.
What can you do to minimize confusion and stress for the program user? Start by keeping these general technical writing tips in mind:
Stay audience focused
- Who is your audience? (beginner program users, experienced program users)
- What does your audience already know? What do you need to explain?
Be concise, easy to understand, and free of errors
- Did you use active voice (doer of action + action word) and verbs (action words) to explain and instruct the reader?
Use accurate vocabulary
- What technical words or jargon is used in this industry? If you’re not sure, ask a subject matter expert. Using a word with a different meaning for the audience could cause a misunderstanding.
Choose effective document design and layout
- Are you choosing headings, bullet points, font sizes, and bolded text to clarify and emphasize important points?
- Are you using media (images, diagrams, and videos) effectively? A diagram can convey complex information more precisely than text.
What Kind Of Technical Writing Can You Do In The IT Industry?
Let’s begin with a refresher on what you could be called as a writer for the IT industry:
- UX writer (UX= user experience)
- UX copywriter
- content strategist
- content designer
- interface writer (interface = program that enables a user to communicate with a computer)
The IT industry has many employment options for writers. Tech writers have a median salary of $71,000+ per year with a bachelor’s degree and less than 5 years of work experience. Click To Tweet If you’re looking for technical writing work, these are some of the areas where you could be a valuable asset.
Software documentation
You don’t need a degree in computer science to write software documentation, but understanding a programming language will put you in the lead for employment opportunities. Tech writers are not developers (also called devs), but it’s handy to at least learn some programming basics.
For example, if you were asked to create code examples for software documentation, having specialized knowledge will be a big bonus.
Software documentation is the written material, images, or video instructions that come with computer software.They explain how to use a program or service. Some projects you could add to your professional portfolio include:
- Requirements documentation that specifies the expectations to the software being created. May include functional requirements, limitations, hardware or software requirements, compatibility requirements, and so on.
- Architecture documentation that define the high-level architecture of the software system being created. May describe the main components of the system, their roles and functions, as well as the data and control flow among those components.
- Technical documentation – documentation of the software code, algorithms, APIs. Written for the technical audience like software developers.
- End user documentation – a set of documents that give assistance to the users of a particular system.
- Internal and external knowledge bases (a library that contains data or information about a particular subject. One kind is machine readable and the other is human readable.)
- FAQ’s
- Video tutorials
- Online help
Software, hardware, web, social media, cyber security
There are many technical writers who used to work in IT who were also talented with writing. There are also many who didn’t major in technical writing. Both types will find work as writers for software and hardware, cyber security, and web or social media.
Defense contractors, software development companies, and hi-tech companies have the highest demand for tech writers. Click To TweetIT applications, products and services
To write for these topics, it’s a good idea if you don’t have a strong tech background to do some research with a subject matter expert (SME). They can provide you with resources for
- Technical content resources, manuals, and user guides
- Industry association resources, studies, and statistics
- Case study examples from real clients
The information that you gather from this research can be used for writing the following:
- IT Services and IT Security
- Mobile Applications
- Technical Products and Services
- Software as a Service (SaaS)
5 Tips To Give You The Advantage As A Technical Writer In IT
As a technical writer, you have the important job of interpreting what the SMEs and developers say and writing it in a form that the user, or audience, understands.
Remember what it was like when you were learning how to use a new type of software? Now imagine having a question about the product.
You read the answer, and you feel even more confused because the answer talks about concepts you don’t understand and you’re not clear if you do step 2 after finishing step 1, or while working on step 1.
Clarity and accuracy are very important in technical writing.
Imagine you’re writing the instructions for a program and you forget to tell the user to press “save” before exiting the program.
This is a straightforward example, but you can imagine the ramifications if the user had finished several pages of writing in a word processing program, or entered thousands of pieces of data for an accounting program.
You get it. To excel as a technical writer, you need to be as concise and error free as possible.
Here are five other tips on how to write and write well for the IT industry.
1. Understand the User
Who are you writing to? Why will they be reading what you’re writing?
To understand your audience, you need to ask yourself questions to get a clearer picture about who they are.
Are they a general audience, or do they have a strong background in an industry? Are they reading your piece because they have questions and they need help, or they’re just reading more information about a product?
Remember that your readers are human beings. A dull piece of writing has never cured anyone of insomnia or boredom.
If you want to connect with the users, your products must have a consistent voice and tone. To decide what tone to use, look at other writing samples from the same company. What is the voice of the company brand?
Mailchimp, for example, is straightforward, yet amusing. Their 404 error pages include illustrations of a monkey in a postal uniform, a banana with sunglasses, and a sausage separated from linked sausages.
When you’re writing copy for these pages, you want your language to match that casual style.
2. Choose Your Words Carefully
What happens when you eat too much? You feel bloated, and you can’t wait to feel normal again. That’s why every word that you write should be chosen carefully. Only use words that you need, and delete words that you don’t.
So if you can say it with one word or fewer words, use fewer words.
Here are some examples of selective editing:
Example 1
Form saved successfully → Saved
Pack as much information info a small space as possible.
Example 2
Compare
“Do you wish to apply this theme? This will deactivate the currently applied theme. Please use Ctrl + F5/R to refresh your browser cache after applying.”
With
“We’ll replace your current theme with this one. If your browser doesn’t refresh afterwards, press Ctrl + F5 or Ctrl + R.”
3. Make It Scannable: The F-Shaped Pattern
Think about the last time you read an article on the web. Did you read every word on the webpage? Or did you scan it and focus on the parts that interested you the most?
Most people read the second way when they read on the web. People rarely read from top to bottom, left to right. If we made a heat map of where your eyes rest on a page, it would look more like a random collection of ink splatter.
Your eyes bounce from heading to heading, stopping on paragraphs that interest you, and skipping over paragraphs that don’t.
To help your user access your content, you want to make it as easily scannable as possible.
The F-Shaped Pattern
People default to the F-shaped reading pattern when reading for the web. That means they read the first line, or heading. Then they read less of the next line. And for each following row, they read fewer and fewer words going from left to right.
Why do they read in this way? Two reasons. First, they are trying to be efficient and not read every word while they look for something specific. Second, they get tired from scanning, and what they are reading is not rewarding enough to continue reading more of the text.
Is it bad to read in this way? It is for users and for businesses because users could be missing important or relevant information that is located on the right side of the web page.
Also, if the user is reading from a mobile phone or a laptop, the viewport changes. The number of words across the screen varies, which means that depending on what device is used, different words could be read or skipped over.
To prevent F-shaped scanning and missing words, make it easier for users to read your content. This is especially relevant for users that like to pick and choose multiple websites while page parking (keeping many pages open concurrently).
How To Direct Your Users To What You Want Them To See
- Use headings and subheadings to highlight the most important points.
- Place the main ideas of the entire page at the beginning. This is called front loading.
- Place the most important points in the first two sentences of every paragraph.
- Bold important words and phrases.
- Use bullets and numbers for lists. Lists are easier and faster to read than paragraphs of text.
- Be specific when you are choosing your words. For buttons, choose verbs that clearly identify what action the user needs to take.
- Explain the “why”. Explain what will happen next if the user chooses an action or click on an option. Users are more likely to complete a task if they understand why they are doing it.
- Check that your links provide information. Instead of “click here”, provide the topic in the link itself. This is especially useful if a user is hearing the link read aloud on their device.
4. Use Plain Language
Have you ever tried watching your favorite movie in a foreign language? Suddenly you’re not watching the movie for the story anymore. It’s become a decoding game where you’re figuring out the conversation from memory. Not so fun.
I learned English as a second language, and from my experience, I know the importance of getting your message clearly across to your product user.
It’s important to use plain language whenever you write. Even if you are writing to an audience of experts, use plain language. It’s what you use when you write to other people. Write using the same language that your users do. Don’t sound like a robot and use technical jargon to impress experts.
If using a technical term is necessary because it has a more precise meaning, write out the word followed by the meaning of the word when you use it the first time.
Writing In Plain Language
- Sentences should be no more than 15–20 words with one idea per paragraph. You can write paragraphs that contain only 1–2 sentences if they clearly explain the paragraph’s idea.
- Use active voice instead of passive. So instead of saying, “The problem is being investigated” say “We’re investigating the problem.”
- Also, use verbs instead of nouns when possible. For example, change “We’ve started an investigation of the problem” to “We’re investigating the problem.”
- Consider the emotional state and context of the user when choosing what content to write. For example, a user checking flight information might not want to see the pop up message, “The app found information about previous crashes. Would you like to send this data to the developer?”
Writing in plain language doesn’t mean “dumbing down” the content. Plain language clarifies the message for everyone, from the general public, to experts, to international users that speak English as a second language. Click To Tweet
It also makes your content more easily searchable and give it a better SEO ranking because you will be using words that people are entering in search engines.
Another reason for using plain language is readability for technical topics on the web. Even highly educated readers prefer plain language.
For example, a nurse practitioner with a doctorate in nursing compared two versions of an online article on opioid treatments. One had big words and longer sentences. The other was written in casual language.
She said, “This one [revision] is better. I like the larger headings. It’s much more succinct. There is not as much fluff…You can slam dunk this a lot faster, depending on what you are looking for.
“I get feeds all day long from medical things and I peruse them and see if something interests me…. [Reading the revision] would be easier for me … because I [can] see quickly what the issues are. The headlines are nice, bullets are nice. This is a better format for a medical feed.”
5. Give Yourself Extra Time
Remember the last time you rushed to complete an assignment and you made one or more mistakes?
You can reduce, even eliminate your mistakes if you give yourself extra time. Avoid completing a piece of writing right before it is due.
Check your writing for spelling and grammar errors. These are much harder to find if you’ve written a long document. A couple of software tools you can use to help you with editing are:
- Microsoft Word Spelling and Grammar with the Readability Measurement
- Grammarly
But don’t just rely on software. Read through your own writing with your own eyes in case there is something the software missed.
You will also need time to review it with subject matter experts (SME), such as the program developers, a peer, or a supervisor.
Summary
What is technical writing? It’s communication about specialized topics, communication using technology, or providing instructions on how to do something.
What kinds of technical writing will you do in the IT industry? There is a wide range of technical writing options that include software documentation, writing for the web, IT applications, cyber security, online help, and product information.
Five tips will give you an advantage when you write for the IT industry. Start by understanding the user and writing in a language that is familiar to them. When you write for the web, use the F-formation, and make your text as easy to scan as possible.
Use plain language, whether you’re writing to a general audience or to experts. And finally, give yourself enough time to review your work.
Get Early Access Now…
