Salmagundi within Documentation

According to Meriam Webster, Salmagundi is:

1. A salad plate of chopped meats, anchovies, eggs, and vegetables arranged in rows for contrast and dressed with a salad dressing

2. a heterogeneous mixture : POTPOURRI

Salmagundi is also a name of various publications throughout the years. But I don't want to turn this post into a salmagundi. So, I digress.

While salmagundi might be a tasty dish, it doesn't taste good in documentation. Unfortunately, salmagundis are a common problem within documentation. Salmagundis obscure, confuse, and can lose the reader. They're bad, especially when your reader needs to learn critical information. What do I mean by salmagundis in documentation?

It's when documentation goes onto over-technical tangents or tries to cram too much information into one document, especially if it's irrelevant information. So much so, you end up with a technical word salad. But sadly, this is the state of much technical documentation out there. I can't count how many times I've seen this be the case. So how do we avoid creating technical documentation salmagundi? Here are some tips. They're not exhaustive but they should help.

Know Your Audience

This is the key to start your documentation. If you know your audience, you'll know how much information to include, how much to leave out, and what kind of information you need to write.

Know What You're Documenting in 1 Sentence

If you understand what you're documenting, this makes a big difference. If you can sum up what you're documenting in one sentence, you'll know where to go. For example, if I said "I'm writing about how to make coffee," then this will direct what steps or information that I need to write. 

Focus the Documentation

If you focus on what you're documenting, this reduces the chances of it becoming a technical word salad. You'll know what points you want to write about. For example, if I were to create a user manual on how to run coffee maker, I'm only going to show you on how to run the coffee maker. I'll include some troubleshooting tips. I might even include the suggested amount of coffee for each scoop to put into a filter. But nothing beyond that. If we don't focus our documentation, we'll get lost in our writing. And that won't be helpful to anyone.

Leave Out Irrelevant Information

This is an extension to the previous point. But it's worth noting. When you write a document, you need to leave out the irrelevant information. You can overwrite by including every tidbit of information about something. But you risk confusing your readers, especially if the information is irrelevant. 

Back to the coffee maker example, I'm not going to mention how the coffee maker was made or what kind of roast would be best. Or even, how to store your coffee. All these points are irrelevant on how to use the machine. You only need to know how to run the coffee maker. Anything else confuses audience or distract from you need to know. 

There will never be an end to the information you can bring up. But a lot of it is neither relevant nor helpful to your reader. So if strays from the point of the document, leave it out! Once you finish writing the document, look through it again and cut what irrelevant information that remains.

I love what Mark Twain once said about books. And I believe it applies to documentation. Twain said:

"A successful book is not made of what is in it, but of what is left out of it."

Consider Multiple Documents

Now there are times when you need to cover a lot of information. Just listing steps to your reader might not give them the whole picture about a product or service. If you run into this situation, then consider writing multiple documents. 

So if someone goes through the steps to run a coffee maker but needs to know to grind coffee beans and store them, then write two other documents. One is how to grind the coffee beans. The other would be best practices to store the coffee beans. Breaking down in smaller, more focused chucks goes a long way.

Especially now, when a lot of documentation is digital. You can write short documents and hyperlink them to each other. So, if a reader needs to find further information, they can go to the document that's relevant to them instead of thumbing or scrolling through one big document to find it. 

When I first started technical writing, we would jam as much information as we could into one document. We would sometimes break it into a couple of volumes. But we were doing this because of printing costs. But now, creating digital documents is a fraction of that cost. Sometimes, you can create digital documentation for free. So, there's no excuse to jam everything into one huge document, especially if you only write digital documents. So break up the documentation into easily, digestible information. 

These tips should help keep the documentation focused like a themed dish instead of a salmagundi. It won't be perfect because no documentation is. But, it should go a long way. Keep on writing.