6 Things That Spoil Your Documentation

Simplicity in technical writing is the key to success. Your document should be efficient, readable, and understandable. It should perform its function well and be comprehensible.

So, here are the things that may spoil your documentation.

1. Poor Structure

The first and most important problem is to arrange the structure of the document. The logical structure of the document contributes to its sense and purpose. Poor structure ruins it all. Use a scheme or a plan before writing. Ask yourself whether your structure is helpful in understanding the information and sense of your text. If you do not think so, it is a great idea to improve it. It is the bases of your text. It simply cannot be poor.

2. Long Sentences

It is really hard to read long sentences containing a lot of homogeneous, compound, and complex parts. Divide lengthy sentences into two or three short ones. If you have enough breath to pronounce your sentence, it means it is easy to be grasped. Look through your text and check whether you lose the train of thought while reading. If you do, your text needs simplification. You wrote it to give the reader clear information but not to confuse and puzzle anyone.

3. Complicated and Long Words

Sometimes technical writers tend to use complicated and long words and phrases in their documents as they sound more important and add value to the text. Once again it affects the simplicity. You can substitute complicated and long words by their simpler synonyms. Of course, this does not work with specific technical terms. Once again revise your text to see whether you really need all those complicated words and constructions. You can collect all your favorite ones and find simpler synonyms for them. Step by step you will get used to them.

4. Poor Layout

If your text looks like a whole endless passage, I am 100% sure that it is a problem to read it. Anyone may get lost in it. Divide your text into sections, paragraphs, smaller parts. It contributes to readability. Check whether it is easy to find information throughout your text. Most people do not read the whole document. They look through it and pick up the passages that they need most. If your document is informative without detailed reading — great job!

5. Lack of Visual Content

Visual content contributes to the easy perception of information. Numbers in a text may get lost affecting its meaning in a negative way. Tables and diagrams can simplify even the most complicated data and keep them clearly readable. Pictures and sketches can illustrate your descriptions making them perceptible.

6. Inconsistency

It is essential that you should use the same standards and styles throughout your technical documentation. The same terms should be used from the beginning to the end. Inconsistency may confuse and disorientate the audience. That is what we are eager to avoid in technical documents. It is a great idea to check a document once again to make sure everything is ok. Especially when you are working in a team.

Think about your readers — write in a simple way. Avoid ambiguity and create the most informative documents.

Have a nice day!

Bradley Nice, Content Manager at ClickHelp.com — best online documentation tool for SaaS vendors

Source:  https://medium.com/level-up-web/6-things-that-spoil-your-documentation-81ab7b21ed61

Written by

Bradley Nice
Content Manager at https://medium.com/level-up-web 👈. I write about web design, web development and technical writing. Follow me on Twitter and Facebook
Level Up!

Level Up!