We often get wrapped up in producing documentation quickly to satisfy the next milestone or to meet a deadline. When we do this the concept of writing to an audience is sometimes lost. Here are some tips on writing for the reader instead of the job. Keeping the audience in mind helps us communicate our concepts.

Acronyms

Always spell out an acronym and place its abbreviated form in brackets afterward. Do this the first time you need to use it. This gives the reader a quick reference that isn’t a glossary located pages away from where they are reading. If you find that the document is quickly filling up with short forms, consider creating an alphabetized list of acronyms near the beginning of the document.

What is Your Reader’s Knowledge Base?

Does your reader have a technical background? If not, cut back on the jargon and take the time to explain concepts in plain English. Don’t think of this as a license to waste pages though. Be mindful of how much the reader needs to know and what they already understand.

Keep Documents Accurate

Almost all of our documents begin by being derived from other documents. This means the new content might accidentally include information from another project. Specific details that only apply to the source document, like input voltages, transformer ratings, or equipment tag numbering, will be misleading. Imagine your reader tearing through drawings looking for a relay that doesn’t exist! To avoid this, consider reducing the project-specific content as much as possible, and then cross-check the document against related drawings and data sheets to get the variables right.