We read and write a number of documents related to different topics every day. And, sometimes we want to create a better structure in our technical documents. Sometimes, we want to use better structures for our technical documents. A couple of months ago, I took an online training course to improve my writing skills. I think the training was excellent. It provided useful instruction(s) and showed how to use structures in a technical document.I felt that I should share my notes to help others.

There is a couple of topics that we need to know about technical writing.

Avoiding Common Writing Mistakes

Your writing should be as clear as it can be. And we need to avoid common writing mistakes in the environment.

• Most of the readers don’t have good knowledge about your writing. Using inappropriate jargon in your document is not appropriate for the audience. You can use the jargon that your audience will understand
• Cluttering your document with unnecessary details. Don’t make too many words to make your point.
• Avoiding long-winded expressions. You can remove unnecessary words without changing your meaning
• Steer clear of tautologies.
• Use a list instead of paragraphs where you. If you have clear instructions in your document, the list would be a better way then a paragraph.
• Using short sentences is an excellent way to explain your thought. When each sentence contains one idea, it is easier for the audience to understand. Using unclear sentence structures makes your writing more complicated.
• The sentences should contain an active voice. Because active voice sentences are more direct, and usually, the text created is more precise.
• Avoid confusing similar words. Some words in your document sound look the same, but it is not. For example, words like “Affect” and “Effect.”

Planning What You Are Going to Write

You don’t need to architect to plan your writing. But you can follow a five steps process for your document.

• Develop a timeline for your work: Writing contains four phases, prewriting, drafting, revising, and proofreading. In each step, you need to carry out specific tasks. And you need to add each task to your timeline and set a timeframe for each one of them. In that way, you will arrange to meet your final deadline.
• Create a statement of purpose: This section you need to add the reason why you are writing, which helps you identify all the information you will need.
• Decide on an organizational style:
  • Chronological Style:
  • Comparison approach
  • Cause and affect the style
• Compose an outline
• Create a draft

Creating Clear Instructions

Instruction is essential for technical writing. The instruction that is written poorly makes the reader frustrating. There are a couple of things to help you write good instructions.

• Analyze your audience: If the audience is not familiar with the subject, we need to avoid using too many jargons. If they are familiar with the topic, we don’t need to explain too many this and waste time
• If the instructions in your technical writing will be used once, you can directly get to the point. But if the instructions will be used much time, we need to add more details about the instructions.
• If you have different types of audiences, you may need to create multiple sets of instructions.
• Instruction should be clear and direct. So we need to choose the word carefully.
  • Use imperatives
  • Be concise
  • Be specific
  • Use plenty of action words
• Present the steps in chronological order. The reader should be able to see exactly what has to be done in order. You can use some bullets points to separate the steps.
• Consider the structure of the document as a whole. You will need a few elements to make everything is clear.
  • Title
  • Introduction
  • Extra requirements
  • Steps
  • Conclusion

Training by Writing

• Create learning objectives: Learning objectives identify specific tasks or knowledge the learner should be able to demonstrate after the training is completed. Objectives should use action words. And it should be measurable and observable. So you can test the learners ’ met the goals.
• It would be best if you made sure that all the content in the training document should be accurate. Inaccurate information in the material frustrates people. Also, it affects your meeting the objectives in a different way.
• Asses how well the learner achieved the learning objective. You can add some case studies or role-plays in the document. Case studies are written exercises in which you present learners in some scenarios.

Writing Reference Materials

If you are writing a reference document like online help pages or technical specifications, you need to keep general guidelines in mind. Basically, the reference material aims to give information efficiently end clearly.

• Be succinct – Use short sentences. So, the reader can find what they are looking for quickly. And don’t put unclear and unnecessary words.
• Order the information in manageable chunks — readers go-to reference material and when they need specific information quickly. So we need to break up the content of our document shorter, meaningful, and manageable chunks. Each chunk should deal with only one idea or concept.
• Order the material logically. To make it faster to the reader to find what they need. Your order will depend on your content. You might create an alphabetical or chronological order.
• Keep within scope. Don’t give extra information beyond what the reader needs to know.
• Make sure you use appropriate language. The right approach for this, we need to use analogies, synonyms, and examples in the document. Also, you need to add some definitions in the glossary. That makes readers understand some terms in the text.