The technical writer, this mysterious character

Let’s face it, being a technical writer (especially in Italy) makes you feel a bit like Barney Stinson from How I Met Your Mother: no one knows what your real job is. If you’re a tech writer, we bet you have at least one relative who, at every family gathering, asks you “What do you exactly do for a living?”. In the most desperate cases, even your mom doesn’t know what your job is!

Therefore, in this article we will try to profile technical writers. We will talk about the main objectives, the working method, the necessary skills of a technical writer. Finally, we will briefly describe the figure of the Technical Writer @ Facile.it.

Foreword

Before going any further, a few things need to be clarified. First, it is important to note that the hard skills needed by technical writers vary by industry. For example, a technical writer working in the mechanical engineering industry needs some different hard skills from a technical writer working in the IT industry.

In addition, unlike other professionals, technical writers working in the same industry often have very different academic and work backgrounds. The heterogeneity of backgrounds is particularly evident in Italy since there is not yet an academic path dedicated to technical writing, so this profession is learned through courses and experience. Instead, some universities outside of Italy offer bachelor’s and master’s degrees in technical writing. This makes the profession more widespread and recognized abroad.

However, it possible to define a generic profile of the tech writer despite these differences. We can say that the soft skills needed by technical writers are cross-cutting and do not change based on the industry. Moreover, there are some fundamental hard skills that every technical writer should possess, regardless of the business sector.

What follows is an effort by the Technical Writing team at Facile.it to get our professionalism known and to unveil a few mysteries by providing a little introduction to the technical writer role.

Main goals of a technical writer

Regardless of what industry you work in and what product you write about, one of the main goals of a tech writer is to make complexity (of a product, process, etc.) less complex.

We believe that simplifying complexity is a necessary step toward achieving a greater goal, perhaps the goal of technical writers, which is to help other colleagues, the users of a product, or anyone who might benefit from documentation. The primary goal of our work should always be to relieve people of the difficulty and frustration that comes from a lack of knowledge sharing. We like to think that the technical writer’s work, in its own way, is altruistic work.

We talked about knowledge above because, if we wanted to summarize our work, we could say that our mission is to capture the knowledge of said products or processes and make it available to colleagues or to external users (e.g. partners or customers). In fact, this knowledge is often scattered within the company and often relies on oral tradition. This creates disaffection among a company’s employees, among its partners, and among its customers.

How does a technical writer typically work?

Now let’s try to understand what actions a tech writer usually performs. Of course, the work processes and procedures vary depending on the methodologies applied by the company and the team to which the writer belongs. The following actions identify the main tasks of a technical writer.

1. Gather materials needed for the task/project.
2. Plan the work for the task/project.
3. Study the available material.
4. If necessary, “play around” with the product to analyze it and begin to learn about it.
5. Interview Subject Matter Experts (SME) to understand how the product/process to be documented works.
6. Interview some of the possible users and stakeholders of the documentation to learn about their needs.
7. Begin writing the documentation.
8. Conduct additional research and/or schedule additional meetings with SMEs.
9. Write some more…and more.
10. Request revisions and implement revisions.
11. Publish documentation.

What are the hard skills needed by a technical writer?

As mentioned earlier, hard skills change by industry. However, in general for a technical writer it is helpful to:

• Know how to use CMSs and text editing tools that are specific to technical writing (e.g. Flare, Paligo, Confluence, ClickHelp, Oxygen, FrameMaker, etc.)
• Know how to use image and video editing tools (e.g. Snagit, Illustrator, Photoshop, etc.)
• Know HTML, XML, and CSS. A basic knowledge may be sufficient.
• Possess excellent knowledge of English language and grammar, for both native and non-native speakers. Yep, being a native speaker doesn’t mean mastering the language perfectly.
• Possess excellent knowledge of another possible language in which documentation could be written (e.g. Italian for us).
• Know the rules of Simplified Technical English and other controlled languages (e.g. Italiano Tecnico Semplificato).
• Have good project management skills.

For technical writers working in the IT industry, it is also helpful to:

• Know Markdown and/or reStructuredText.
• Know Git and the Docs-as-Code approach. A basic knowledge of Git may be sufficient.
• Be familiar with some of the programming languages used in the company (e.g. JavaScript, PHP, Phyton, etc.). A basic knowledge may be sufficient.
• Know how to write API documentation.
• Know some modelling standards (e.g. UML, C4, BPMN).
• Know how to work with Agile methodology and tools (e.g. Jira, Trello, etc.)

Obviously, each person possesses and practices each skill at different levels, depending on their aptitude and personal tastes. It is not necessary to have perfect knowledge of everything listed above.

Certainly, as with many other jobs, two key aspects of a technical writer’s professional life are training and keeping up to date with industry news. There are many ways to achieve these goals, for example: taking courses (both online and in-presence), attending conferences, joining industry associations and communities, reading trade journals and blogs. Below are some references that can help you navigate the jungle of technical writing.

Courses

Courses are available on major platforms dedicated to training (e.g. Udemy and Coursera) or you can purchase them from specialized companies that sell their courses. You can often find courses on many useful topics at affordable prices. In addition, industry associations offer courses and workshops. In most cases it is convenient to pay a membership fee in order to benefit from these courses and workshops at a discount from list prices. Industry associations also organize courses aimed at obtaining official certifications.

Conferences

As for industry conferences, we will mention only the main ones which are: Write The Docs conferences, soap!, STC Summit, tcworld conference, Evolution of TC, and COMtecnica. We suggest evaluating the conference programs and choosing the one most relevant to your industry.

Industry associations and communities

Also in terms of industry associations and communities, we will only mention the main ones which, as you can imagine, are the ones that organize some of the conferences mentioned above. These associations or communities are: STC, Tekom, Write The Docs, and COM & TEC. We also suggest joining groups on LinkedIn or other social networks.

Journals and blogs

Some interesting magazines and journals in this field are: tcworld magazine, technische kommunikation (in German only), Intercom, Technical Communication, and The Journal of Technical Writing and Communication.

Some of the blogs we recommend following are: I’d Rather Be Writing, ClickHelp Technical Writing Blog, Scriptorium, and TechWhirl. Also, you can find noteworthy articles on blogging platforms (e.g. Medium).

What are the soft skills needed by a technical writer?

After talking about purely technical aspects, let’s try to focus on personal qualities and see what soft skills technical writers must possess. It goes without saying that even in terms of soft skills, a technical writer is not expected to master all of these skills to the highest level.

Whatever the industry they work in, these are the soft skills that are useful to technical writers:

• Ability to create and maintain relationships
• Ability to mediate
• Ability to learn quickly
• Curiosity
• Adaptability
• Time management
• Precision and attention to details
• Proactive listening
• Courage…to ask for help when necessary

Technical writers @ Facile.it

We will conclude by describing the reality in which we work on a daily basis. We will briefly tell you about the technical writing team of Facile.it.

Since Facile.it is constantly evolving and growing, also our team and its organization will surely change in the future. In fact our goal, as well as that of the company, is to constantly improve. Therefore, we do not claim to be a perfect model, we are constantly self-critical and we are aware that there are many realities out there from which we can learn.

However, in the meantime we are pleased to introduce ourselves and tell you a little about us.

Our team within the company

Our team is part of the IT department, more specifically we are part of a bigger cross-functional team called Platform Team. From our positioning within the company, it is easy to understand that we work in support of the other teams in the IT department and that we are a link between the IT department and other “worlds” within the company, for example the Marketing, Product, and Business departments.

What we do

These are the main activities we handle:

• Recover the documentation debt for old projects, when needed for refactoring and decision making.
• Create documentation for new projects. These documentation can either be strictly technical or it can also deal with business aspects.
• Create ready-to-use standard indexes and templates for colleagues (e.g. an index for software project documentation, a template for the documentation of microservices).
• Provide consulting to colleagues who ask us for advice by giving them suggestions and links to tools that may be useful.
• Review the articles on this blog from a formal and linguistic standpoint.
• Keep up to date through courses and conferences and research tools and methods to improve our work.

What we do not do

On the other hand, these are the activities we do not handle:

• Create day-by-day documentation that is in charge of each team (e.g. meeting notes, minutes of retrospectives, maintenance documentation, release notes).
• Proofreading and editing. We are available for suggestions and minor changes to documents written by others but we do not carry out review projects.
• Create documentation for marketing/commercial communication.
• Cover the lack of documentation of third-party applications used within the company. We are available to document custom integrations developed internally, but we do not write full user-manuals of external applications.
• Translate documents written by others from Italian into English and vice versa. When necessary, we translate documents written by us.

How we plan and organize our activities

Our team plans quarter-by-quarter activities, trying to align with business needs as much as possible.

However, as we said above, the company is constantly evolving and growing, and we can’t deny that sudden changes have sometimes interfered with the planning of our activities. We didn’t lose heart over it, though. We spent a team retrospective to figure out how we could improve our processes and anticipate needs in the best possible way.

Therefore, we created a form through which technical writing requests can be submitted and we provided instructions on how to fill it out. Through this form it is possible to request the creation, updating, and correction of documentation. The requests received will be analyzed and discussed by the team before being taken up, put on hold or rejected. Currently, we plan to activate the form for two weeks straddling two quarters.

We chose to follow this approach because the current size of the Technical Writing team does not yet allow to allocate a technical writer to one or a few IT teams. Not being able to follow the daily activities of a team, we looked for a solution that would allow us to know the “macro-needs” of our colleagues in advance. Is this the best approach ever? Probably not but it is the approach that best fits the current organization and structure of our team within the company.

Conclusion

Through our daily activities, we are proud to contribute to the simplification and dissemination of knowledge in the company. Therefore, we hope that this article helped you learn more about our profession and made you a little curious since the acknowledgement of the technical writer’s role and support from colleagues is critical to do this job well.

Of course the article cannot be exhaustive since, as you may have noticed, there are many shades and points of view to consider. However, we are pleased to contribute to the definition and knowledge of this profession that can offer many opportunities and is constantly growing and evolving.