The Written Word in IT
For those working as engineers, developers, database administrators or in other IT job roles, writing (documenting) can be a large part of your job. However, in such job roles, writing often involves taking extremely technical information and transforming it into laymen’s terms. It can be extremely difficult to take technical information, which makes perfect sense to the writer, dissect it and then relay it to people who are not experts with the subject matter.
In writing, two kinds of jargon exist: technical and gobbledygook. Technical jargon although common in IT, can be extremely confusing for end users. However, technical jargon is only appropriate if the documentation is intended for others in your profession. That’s why it is extremely important to know your audience. For example, if you were writing about the latest version of a unified wireless network and how it could be applied in the field, your intended audience would be the head of an IT department or senior leaders of an organization. Therefore, the documentation could be slightly technical, but should mostly explain the impact such a network could have on the business.
Gobbledygook, on the other hand, simply adds confusion. Gobbledygook is also very common in today’s modern society, where words created by rappers like “Fo shizzle” are used readily—even in the workplace. Hopefully, it is unlikely that a direct report would say “Fo shizzle” to his or her boss.
So how can you ensure that information is written in way that end users can understand it?
- Identify your audience. Make sure that you know your audience—meaning their skill level, knowledge and experience—before sitting down and writing.
- Translate first. Take the information that is critical yet extremely technical and put it into laymen’s terms, if necessary, before sitting down and writing.
- Apply the three Cs of writing: clear, concise, correct. Make sure that the information is clearly written: Include definitions, take the time to describe what something looks like, etc. Be concise and eliminate all extraneous information. Finally, make sure that the information is correct, accurate and precise. If an error is present—especially in technical documentation—the effects could be disastrous.
- Have an audience member read the information before it is distributed. The best way to know that your information is clear and concise is to have a prospective reader read the information. This person will be able to identify confusing terminology, blatant errors, etc.
- Read it aloud. Reading something aloud is an excellent way to make sure that something is written in laymen’s terms. Have you ever tried to read a medical dictionary aloud? Well, it is difficult—especially if you are not in the field. Reading aloud helps you edit, find rough patches in text, eliminate jargon and more.
Remember it is critical—especially when writing for end users—to eliminate technical jargon. Technical information can make end user’s eyes glaze over, give up on learning the processes and lead to making needless mistakes on the job, which will make your job, in the end, more difficult.