Manuals, Guides, Presentations… What does it mean to write in a way that best communicates the value of technology? Is it enough to list product or service features, specifications, installation, troubleshooting? Here’s a quick walkthrough of how we can best communicate the value of our product or service through written content.
The importance
First, consider the importance of the content being written. There are contracts and regulations that require a manual, for example the EC Machinery Directive, but more generally, if a written document is required, why not make it a strength? Well-written, clear and effective instructions decrease support requests, complaints, risk of damage and disruption. It benefits the product and company image. Training and support costs are reduced.
The audience
It is crucial to know the target audience well, in terms of profiles (personas). We are writing for them. We should always keep that in mind. Who do we want to reach? What kind of preparation and what kind of skills do we expect them to have? What are their goals in using our product or service? A typical risk is to include too much descriptive detail that is not useful to the recipients and instead fails to provide all the instructions necessary to achieve their real goals.
The product (or service)
All data and elements of the product or service in question must be fully mastered, of course, through the necessary technical and application skills, usually distributed among several Subject Matter Experts (SME). Writing technical content means bridging the gap between these experts and the intended audience. The technical writer builds it by walking it first.
The model
Of course, you should never start from scratch. Depending on the document or format, use the template that defines the best corporate structure and format, ensuring completeness and compliance with all applicable standards. Many parts will be common and repeated in other documents. This eventually becomes complex to manage manually each time, and there are tools to optimize the reuse of common parts: the CCMS systems, where CCMS stands for Component Content Management System.
The writing
It is important to remember that we are writing technical content for a specific audience that has practical, concrete goals. Therefore, we must use an appropriate writing style. In short, here are the qualities to consider:
- Conciseness: Since reading takes time and effort, we always get to the point in a direct and brief manner.
- Clarity: It is of course essential to make oneself understood. Have we thought about it, reviewed it, and then had it verified?
- Terminological consistency: Avoid unnecessary synonyms and follow the (necessary!) technical glossary.
- Graphical structuring: organize text into sections with headings, subheadings, and lists as necessary.
- Simplicity: Use a plain writing register. Make a useful (and common sense) reference to the standards of the technical language [1]. Style Guides for the collection of general rules of the language and business norms can be useful.
- Accuracy: In every technical detail and especially in figures, units of measurement (adapted to the target market), technical and regulatory references, and especially in safety standards.
- Logic: Strictly follow the logical order of work instructions and their individual steps, linking instructions as appropriate to achieve all intended results.
- Illustrations: Ensure clarity and effectiveness of images and multimedia. Don’t forget to consider translation plans and potential issues.
- Structuring: Organization of the sections and modules [2], in particular the instruction procedures, the reference tables, and the troubleshooting information.
- A look to the future: especially artificial intelligence tools.
The test
Any data or technical information is only accurate if it is verified and tested in the field. This is usually done with the help of a technical expert. Then, let’s rigorously verify our content through formal reviews appropriate to the current business process. User Experience (UX) is the main method in the design theme with constant verification.
The translation
Market regulations and opportunities often make it necessary to translate documentation into the language of the target country. Translation should not be underestimated and should be well managed to avoid poor results and additional costs. Here is a helpful checklist:
- Translating a final, stable version of the content. If you need to start before completion, you can get there with two or more or steps.
- Always maintain a technical glossary of company and product terminology.
- Use advanced computer and machine translation tools [3] without omitting or delegating the translation memory, and always check the results with experts.
The maintenance
Once the technical content has been written and reviewed, it can be used for all kinds of purposes (it is a valuable business asset). It will then need to be updated over time for corrections, fine tuning, and product evolution (variants, versions). Once again, the use of more advanced tools will allow for better maintenance management.
If you are interested, please contact us for a free in-depth discussion.
Notes
- Here are the most important technical language standards. They contain general rules and dictionaries. Note that they should be used with common sense. They may be too rigid or not completely up to date.
- ASD-STE100, or Simplified Technical English.
- Italiano Tecnico Semplificato (ITS), edited by Associazione Italiana per la Comunicazione Tecnica.
- Español Técnico Simplificado (ETS).
- Français Rationalisé (FR).
- There are standard formats for structured documentation, the most widely used of which is DITA (Darwin Information Typing Architecture). SCORM for training materials and S1000D for defense and aerospace.
- Computer-Assisted Translation (CAT) uses specialized programs to facilitate manual translation and keep memory of translated sentences (TM, for Translation Memory). TM allows to optimize subsequent updating of the original translated text.
Machine Translation (MT) is handled entirely by artificial intelligence tools, which can help but cannot (yet) completely replace human activity, at least for careful verification of results.
