Best Practices for Technical Writing

In a world where technology develops by leaps and bounds, where every day a new application or software solution is developed, and where these technological developments are released together with their technical documentation, today more than ever, the skills of professional technical writers are required and essential to meet these needs, to create and publish technical documents at the same high speed. But, what do technical writers do? In short, we are responsible for turning technical and complex jargon into user-friendly language. We make the reading of manuals a pleasant activity. And, as part of the documentation team in Intraway Corporation, a technology company which is constantly innovating and developing solutions, we consider that we can deliver even better services thanks to different practices we have adopted. Thus, we would like to share with you the following best practices in order to successfully link the art of writing with the science of technology:

Appropriate Office Conditions

Like any writer, we usually spend long hours sitting at the desk in front of our computers, so it is very important to have suitable office conditions to do our job comfortably, as well as to take care of our health. In our offices we have ergonomic chairs, keyboards, and desks, to mention some features, but what really makes the difference is using large double monitors. For example, the document that we are working on can be displayed on one screen and the application to be documented on the other one. In this way, we are able not only to view all what we need at the same time, but also to work more efficiently and faster.

Information about the Product

In order to start writing, we need any sort of information about the product and as much of it as possible. That is to say, we need to know how the product works and behaves and how to use it. The sources of information may vary from functional specifications to presentations. As we need to become experts on the application we are documenting, it is fundamental to conduct some research on the product. For instance, we may request access to the business-unit drive so that teams can share their documents with us. Once we get all the available information, the following step is to read it thoroughly, organize it, and outline our document.

Testing Environments or Mock-ups

Up to now, you are sitting at a comfortable desk; and you have gotten some information, so you can probably start writing. However, there is still another useful practice: having access to testing environments or mock-ups of the products. In this way, we can take high-quality screen shots, follow the use cases described in the internal documentation, compare the obtained information with the actual product, check how it works and learn how to use it. This practice results in a comprehensive, well-organized and detailed document.

Content Quality Assurance

After finishing a piece of writing, and before publishing it, it is also crucial to edit it. We usually resort to a peer review within our documentation team, and then, we deliver it to the product manager who carries out a thorough reading and careful quality assurance. This helps us to improve the quality of the documentation and to improve ourselves as specialized writers.

Collaboration and Communication

During the whole process, we are in permanent contact with the experts; in our case: the developers, functional analysts, product leaders or product managers. Let me give you some examples to illustrate this practice: we hold meetings with them, or we just go to their desks and ask them for further explanations, we also send them monthly newsletters with details of the documents that are in progress and scheduled for publication. As you can see, there is also a sort of collaborative relationship. We provide them with our service and our expertise to write their manuals and to define the document architecture suitable for their product. And they provide us with their specialized knowledge and point of view as they are the owners of the product.

We hope that all this information can be of help to you. We are sure that there is still more to do and to continue building together.

Biography

I work as a Technical Writer for Intraway Corporation. I hold a Translation degree and have more than five years of experience as a technical translator and proofreader.

 

Analía García
Intraway Corp.
Technical Writer
Email: analia.garcia@intraway.com

 

Menu