Technical writing — writing about a specific topic and its techniques — is an important part of building materials for any SaaS business. You might use it in the Help section of your website, in your product descriptions, in a blog post, or even in e-mail help services.

Whatever you’re writing for, your technical writing has to be on point or people won’t want to read it. That’s a problem, especially for SaaS companies who put a lot of technical writing on their websites and blogs. The writing has to be informative, concise, and accurate or people won’t learn from your site and engage with your brand. Bad technical writing will immediately bounce people from your page, and maybe even from your software.

But although technical writing takes a lot of skill, many people tasked to do it don’t have a background in writing at all. Short of going back to school, improving your writing skills can feel like a daunting task. It can be hard to tell if you’re making real improvement.

That’s why we’ve outlined ten tips to help with technical writing, from structuring to writing mechanics to media and widget additions beyond the words. These aren’t just one-and-done suggestions—they’re tools of the technical writing trade. Learning how to master each one will give you an arsenal of techniques to use when you’ve got to write.

1. Signposting

All expository writing improves with good signposting. Do not overlook something as simple as making clear, informative titles and subtitles for each section. Don’t be afraid to boldface your key points, or use a sparing use of color to emphasize key points. These will signal to the reader what they’re learning and what they should pay attention to.

To see if you’ve given your reader enough direction, try looking at your finished piece and just writing down your title, subtitles and any bolded or offset text. Do you get a clear outline of what the article is about? If you handed that to someone, could they fill in the blanks and rewrite your article? If yes, you’re hitting the sweet spot.

And, while most people underemphasize rather than overemphasize their points, make sure you don’t go overboard. If you mark everything as important or give every paragraph a subtitle, you’re signaling that nothing is important.

(Source)

2. Mutually exclusive, collectively exhaustive

Mutually exclusive and collectively exhaustive is a way to organize your content. You want each section to be separate from every other section, but together they should give the reader all the information they need on your topic. Say you were teaching someone how to make a PB & J from scratch. You wouldn’t want to talk about slicing the bread in two different sections, because that wouldn’t make any sense and it would be redundant—but you also wouldn’t want to forget to mention to add the jelly, or you can’t make the sandwich.

A great way to see if you’re on track for this is to check those signposts. What is each of your sections labeled? Do they have any overlap? If not, then read through those sections and see if you stick to your topic in each one. Although it can be tempting to blur the lines, if all your sections together are collectively exhaustive, you’ll cover everything even though you’re sticking to one topic at a time.

3. Diagrams

Why say it in words when you could simplify things with a graphic? There’s a million different types of graphics, diagrams and DataViz that will simplify and clarify your concepts. They might not replace all your writing, but they can enhance your points. If you’re talking about data, use graphs. If you’re talking about planning a logical sequence, use a flowchart. If you’re presenting a timeline or background info, try an infographic.

If you aren’t trying to demonstrate a concept that easily lends itself to graphical representation, there is still a place for diagrams and graphics. If you’re writing a blog post or a white paper, tasteful use of additional graphic elements — or even block quotes — will break up your mountain of text and make it more palatable for your reader.

4. Keep it simple, stupid

When you’re explaining a concept or writing in a field that has a lot of jargon, it can be tempting to throw all of your fancy phrases into your article. People think that this makes them appear like they know what they’re talking about, or that it helps them appeal to an in-the-know audience.

In reality, bungling your writing with jargon does the opposite of what you want. You know all those complaints about flowery academic writing that’s all jargon and no sense? Stuff like:

(No offense to this article, we’re just not film buffs.)

Well, if you’re overloading yourself with jargon, you’re doing the technical writing equivalent.

Any piece of technical writing — from a help doc to a blog post — should be clear and concise. Appropriate terms should be used when necessary, but the overall language should be free from hyper-technical terms if they’re not needed.

5. Stop, collaborate, and listen

If you’re a technical writer, or at least someone assigned to do some technical writing, chances are that you aren’t going to know absolutely everything about every topic. When you come up against a concept that you aren’t 100% comfortable with, it can be tempting to fudge your writing a little to cover it up.

(Source)

But wait! Making things vague or brushing parts of your discussion under the rug is only going to weaken your writing! Instead, stop what you’re working on, and go find an expert. Maybe they’re down the hall, maybe they’re on a site dedicated to expert opinions on cryptocurrencies, or maybe they’re in a Slack channel for Python users somewhere. Seek them out and ask them to help you understand your topic.

After you’ve listened to an expert, go back and try it again. It’s worth taking the time to go through these steps if you feel like you’re starting to hand wave your explanations to gloss over your gaps in knowledge. There’s no shame in asking for a bit of help.

6. Calculators

Just like datasets are often best represented in graphs, equations are often best represented with an embeddable calculator. In our list of 21+ embeddable calculators, we summed it up by saying:

A good embeddable calculator can give readers an understanding of things that would be lengthy, cumbersome or even impossible to explain another way.

Our thoughts on the matter haven’t changed one bit.

7. Examples are your friends

If someone has a limited amount of capital to spend and they are choosing between two objects, one of which is for pure enjoyment and the other of which is a necessity that cannot be ignored, which is it more prudent to choose between?

Hold on, let’s try that again.

You have a fixed amount of money. You need to choose between two items to purchase. One is for fun and the other is necessary. Which is it better for you to choose?

Still not quite right — one more time?

Ben only has $50.00 left to spend. Should he buy 15 bottles of orange juice or pay his electric bill?

Whether you make it up or use something from real life, using an example is an easy way to simplify things for your reader and illustrate your point. It can cut down on wordiness and illustrate a concept in a more precise and less abstract way.

This is especially important in technical writing when you’re describing a process of how to get something done. Rather than completely abstracting, take readers through with a demo—and add screenshots or snippets of code where appropriate.

8. Take baby steps

Often, technical writing describes a particular craft or technique. This frequently means that you’re taking a reader though things in a rigid sequential order, whether that’s how to build X from steps 1-10 or explaining a concept that builds on itself.

But when you know that technique well, you might accidentally find yourself making leaps that seem intuitive but are not clear to those who don’t have the knowledge you do.

A great example of this is trying to describe how to make a PB & J. Seems easy enough: bread, jelly, peanut butter, and go. But when you ask people to actually write out a list of steps, they frequently forget to tell the lister to put the peanut butter and jelly sides together, because it seems obvious to them. But if you’re an alien who’s never made a sandwich before, that’s not an intuitive step.

To remedy this, take a leaf out of What About Bob and break things down into baby steps. Especially when you’re writing help documentation or a how-to, you’ve got to be methodical and consistent. When in doubt, break it down. People who know what they’re looking for will skip ahead to the steps they need.

(Source)

9. Pretend you’re lecturing

After you’re finished writing your piece, you probably give it a read- through. But next time, give it a talk-through. Pretend you’re at a lectern and you’re giving a presentation to people who are paying to learn from you at a conference. Don’t just read through verbatim, but paraphrase each section as you walk through.

Does what you’re saying make sense? Are you skipping ahead or going forward to explain as you go? Did you have to give a pretend aside to explain a concept you didn’t put in writing? All of these are red flags that you’re not organizing your information well.

One of the fundamentals of technical writing is having a clear, logical line. Speaking your writing as a presentation can highlight when you’re skipping steps or putting things out of order, because it forces you to rethink how to go through the info. Simply skimming what you’ve written is a passive activity that won’t highlight structural weaknesses as well.

10. Pay attention to writing mechanics

The last thing you should do before you send a piece out is proofread. You can ask a colleague or use a proofreading software to pick up any last-minute errors. This is necessary to ensure that your work is polished and easy to read.

But it’s naive to think that you can fix all writing mechanics problems in a proofread at the end. This is especially true if you aren’t trained in writing. You really need to focus on your mechanics from the start. This is the best way to build up good writing habits, like using the active voice and eliminating unnecessary commas.

Many people don’t spend as much time as they should reaffirming the fundamentals of writing. That’s a huge mistake. There are a ton of online resources that can help you brush up, like Purdue’s Online Writing Lab. If you really want to be a clean, concise and straightforward writer who is taken seriously for their skill, you have to nail the basics.

Practice makes perfect

It’s cliche but true that you need to practice something to get good at it. This is as true of technical writing as it is of everything else.

Don’t try to apply all ten things on this list to your next piece of writing! Work through them one or a few at a time until you feel comfortable. Never used graphics before? No worries, take a couple of pieces to get your graphics skills going. Then move on to killer subtitles. Build your toolbox of skills one at a time and keep going until you’re confident in all of them.