By Technical Communication Ltdwww.technicalcom.co.il

Technical Writing Tips

YOU HAVE BEEN HIRED AS TECHNICAL WRITER OR CONTRACTED AS A FREELANCER BY A SOFTWARE HOUSE OR A VENDOR OF A SYSTEM.

HERE ARE SOME PRACTICAL TIPS THAT KEEP YOUR WORK

WELL-ORGANIZEDAND

EFFECTIVE.

Congratulations,

We are authoring

Know your audience

Tip 1 – Know your audience

Find out who is going to use your documentation, and how they are going to use it. What is the purpose of the document? What need is it intended to fill? Under what physical work conditions will it be used, e.g. at a desk, at a factory workstation, in a laboratory?

These are fundamental considerations, and they determine the character of your document. From the earliest planning stages, and throughout the design and writing of the document, keep your audience and their needs in mind.

Tip 2 – Be prepared

Become literate in the subject you will document before you start interviewing SMEs and other stakeholders. Collect as much written information about the system or device as possible. This will save time in the long run. Sort these background materials according to their importance to your work. Develop a comprehensive list of intelligent questions for the SMEs, considered from the point of view of your audience.

Be prepared

Tip 3 – Collaboration

Tip 4- Prepare the outline

CollaborationFind out who will be responsible for providing the illustrations in the document, and take screen captures. If it is your task, consider the tools and means involved.

Prepare the outline of the manual and get it approved by the SMEs and other stakeholders. Once the outline is accepted, you can estimate the volume and timeline of your job.

Prepare the outline

Tip 5 – MeetingTip 6 – Organize document

MeetingPlan the meetings with the SMEs and other stakeholders in close relationship to the outline.

Use a task-based approach when designing the document’s structure. For example, the Installation section should be at the beginning of the manual.

Organize document

Tip 7 – Template style

Template StylePay attention to how your document will look. Set up a style sheet or adopt a given template from the outset; it can be very time-consuming to change the template at a later stage. At the same time, design the template with enough flexibility that, if necessary, it can be changed with relatively little extra effort.

Tip 8 – Add illustrations

Add illustrations

Illustrations are an integral part of any manual. Illustrate your words as much as necessary to clarify the text, but do not overdo it. Mix text and graphics to achieve maximum clarity and simplicity.

Tip 8 – Be simpleTip 9 – Glossary

Use active voice and simple present tense. Avoid highly academic language. Your reader has neither the time nor the inclination to look up terms in a dictionary. Let the 7-second rule be your guide: the user should be able to locate any piece of information within 7 seconds. If it takes longer, the user will likely give up the search.

Be simple

GlossarySet up a glossary of terms. This will help you to be consistent and assist the reader to look up terms used in the manual.

Verification

Tip 10 – Verification

Before publishing the manual set up a task group to verify your document. The group may include the technical writer, two to three developers or SMEs and one outsider (like a sales person) who have not been involved in the writing process. Ensure that this initiation is supported by a VP. Certain that you will get a dedicated device or workstation for the verification.

Consider localization issues for the future. This is yet another instance of “know your audience”.

We hope these tips will serve you well at your new job. We can help you even more!

For more tips contact us at techcom@netvision.net

or visit our website www.technicalcom.co.il

Good Luck!