The golden rules of technical writing

Written by: Mari-Ann Gripmark

The purpose of technical documentation is to inform the reader about something she needs to know about a product, or to guide the reader through the steps of actions she needs to perform. How well the documentation does this is dependent on how it is written.

Remember, you cannot please everyone! The most important reader to please is the end user of the product that your documentation describes or instructs about. Below are a number of very important golden rules to follow.

Image by pch.vector on Freepik

Golden rules of technical writing:

• Focus on the reader

  • Who is she? Does the user have a specific role in a company, or is she someone who has bought a product for personal use?

  • What info does she need? What does the user need to accomplish in her role or purpose using the tool you’re writing an instruction for?

• Keep it simple

  • Use short, simple words and short, clear sentences.

  • No repetitions or redundant information.

  • No beautiful language or personal touch.

• Make it impossible to misunderstand

  • Be specific.

  • Do not use synonyms.

  • Use the correct terminology.

• Address the reader directly

  • Use active voice: YES: “You can change the configuration”. NO: “The configuration can be changed”.

  • Use imperative: YES: “To turn on the machine, press the On button.” NO: “The machine can be turned on by pressing the On button”.

  • Avoid “should” and “shall”: YES: “Do a backup”. NO: “A backup should be done”.

• Do not mix description and instruction

  • If a descriptive part is needed, put it at the beginning.

  • Make it clear to the reader what she is supposed to do.

Summary: Focus on the reader, keep it simple and concise, be specific, use an active voice, and separate description from instruction.

Our advice to you: There are more aspects of technical writing that can be considered, depending on what kind of document you’re producing and the expected life cycle of the document. But by following these rules, you will be standing on a solid base producing really good material that will be helpful to the reader and also easily translated.

Image by Wix

Being a tech doc consultant - the truth behind the title

Text & Images: Karin Askeroth

What does it take to be successful within technical documentation, and in addition - to be a consultant? As a consultancy company specialized in technical writing and surrounding competencies, this question is always relevant. So here is the truth behind the title tech doc consultant.

The purpose of technical writing is to make technology accessible for the end user. To be a great technical writer, you need the ability to combine the sources of information at hand with relevant outside input to produce content that can be adjusted to be useful for different kinds of end users. It also entails a variety of tasks surrounding technical documentation.

To be a successful consultant, you will need to be an asset to whatever team or organization you’re placed in, and to support them with your specialist skills and expert knowledge.

Would you make a good tech doc consultant?

So how do you know if this would suit you or someone you know? The right mindset is crucial - common sense will get you far but a technical writer also needs to be curious about the end users and how they will use the product. You need to be willing to learn new things, be interested in technology and science, as well as be systematic, detail-oriented, and communicative.

It’s also necessary to be interested in people, your content will be much more attuned to the needs of the end user if you can be open, listen and adapt an audience perspective, which helps you show the end users tolerance and empathy.

As a consultant you will gain success by being a helpful and supportive person, as well as good at building relationships. Other important traits are to be goal-oriented, open for feedback, a quick learner, and a hands-on person. One thing that is very important, but often forgotten, is to be flexible and adaptable, and adjust to the constantly changing processes, requirements and needs.

In short, a successful technical writer consultant is a curious, empathetic person who is detail-oriented, has common sense and is good at connecting with people.

Our advice to you: Many of the traits mentioned can be learned, but you will need quite a few of them naturally to be truly happy in the role as a technical writer consultant.

Are you and informiQ a good match?

Text & images: Karin Askeroth

So you’re thinking about becoming a consultant, and you have your eyes on informiQ? Or maybe your company needs our expertise? In that case you might be wondering what makes us different from other consultancy companies in regards to what we look for in our consultants, what we can offer our consultants, and what we can offer our customers. Well, let us spill the beans for you to see if you and informiQ are a good match.

informiQ is looking for:

All variants of technical writing skills, of course, also in the broader sense including information architecture, document management, and documentation needs analysis.

We are also interested in skills in communication, digital marketing, project management, agile practices, product management, processes and quality, configuration management, UX research, UX design, usability, visualization, and learning.

Ingela, Victoria, and Todd are great examples of competencies that go outside of technical documentation.

informiQ employees are welcomed into a company culture that:

• Welcomes and embraces diversity. No matter who you are, where you’re from, or who you love, we believe you should be you. If you share our values, you are welcome here.

• Encourages internal support of each other, both professionally and personally, and where we have an interest in our colleagues and view each other as friends.

• Regularly have team building activities to widen our perspectives in different ways.

How can you become one of us?

We don’t have any form that you can fill in and present your interest in informiQ. Instead, we work mostly with recommendations from current employees. Another way to make yourself known is to contact us and pitch yourself: https://www.informiq.se/contact

informiQ’s offer to our customers:

Since we hire people with a diverse portfolio, that is also what we can offer to our customers. If you hire an informiQ consultant, you will in most cases get a multi-artist with a broad knowledge base as well as more than one specialization.

Our advice to you: If you’re interested in informiQ either as an employee or as a customer, check out our homepage and see who we are and what our consultancy agency can offer. Don’t be a stranger, we would love to hear from you!