On becoming a technical communicator
By
Joaquim Baptista
Technical writer in Portugal since 1997, plus manager, trainer, developer, and system administrator, riding a motorcycle with Ralph Lauren.
View All Posts
I had the privilege to teach structured writing at the first edition of the Postgraduate Course on Technical Communication at ISCAP (Portugal), sponsored by APCOMTEC, the Portuguese association for technical communication.
The seven students were working professionals looking to change or improve their careers. I was surprised when these students started to question their ability to break into the field, because they will be better prepared than I was when I started. I found myself advising the students by sharing my experience in Portugal and elaborating on my deeper beliefs.
Why will a company hire you?
The 2008 global financial crisis did wonders for Portuguese companies. I saw traditional companies focused on the internal market being forced to seek customers abroad, often for the first time. I believe that companies delivering projects also started to create products.
Portuguese companies were used to communicating with customers through sales pitches, meetings between experts, and occasional documents. These communication practices started to fail when products grew in complexity to accommodate an increasing diversity of remote customers.
When communication failures become a problem for the business itself, the company wakes up to its growing knowledge problem and, eventually, considers hiring a technical communicator (Baptista 2015).
If you join a multinational company, you can easily become part of a small business unit struggling to grow and survive in the context of the overall business.
Why did companies hire me?
I’m a Portuguese technical writer, currently working at Farfetch. I write help and documentation in American English, after gathering information in Portuguese or English. How did I start my technical writer career?
The first company that hired me (Baptista 2014) had the developers write online help for the software. Since the first customer was in Brazil, the developers wrote in Portuguese. Later, the company asked another employee, a native English speaker working in Marketing, to translate the help. The result, however, was to have unclear Portuguese sentences translated into even more confusing English sentences.
The same company asked a large UK technology company for a plan to write the missing manuals. The large UK technology company quoted one person per year to create two 150-page manuals focused on the two main audiences. What doomed the project, however, was the fact that the software was evolving every few months.
Another company developed custom solutions for each customer using outsourced staff, but was trying to create a core product that could be configured to serve several customers. Instead of project-based deliverables, the company needed extensive documentation to transfer knowledge between teams.
A different company needed to figure out the value of knowledge base articles written by support staff as a response to customer needs. These articles had to be articulated with the official company documentation.
Farfetch developed software to support a platform of fashion retailers. When Farfetch allowed other partners to integrate with its own software, Farfetch felt the need to collect and communicate the knowledge dispersed among hundreds of people in our engineering and operations teams.
What will the company expect from you?
If you are the first technical writer in a company, you will probably walk into a mess. You will discover a backlog of work accumulated over years, together with the expectation that you will magically make that backlog go away. You, or the typically understaffed new group of writers, will probably require a few years to tame the backlog.
Your first task will be to understand the knowledge problem and show the company how you might untangle the underlying mess. You will be condemned to do a poor job if you try to tackle the whole backlog at once, especially if you don’t quite understand the reasons for the underlying mess. Instead, pick something small that will make a visible difference and do it well.
This small achievement will show everyone how technical communication can help the company, buying you both allies and time. It will also allow you to learn what it takes to do good work at the company, enabling more realistic plans.
What did I do first?
When I joined the first company, the next minor product release was a few months away. As the sole writer, it was clear that I had no time to learn a complex product and create any manual within that time. Instead, I created extended release notes that explained the new features. It took a few years of creating small manuals focused on parts of the product before we had the first complete documentation.
When I joined another company, I started by documenting a complex configuration file in Confluence pages. Using Confluence meant that the engineers could easily collaborate with me and that the upcoming documentation was immediately available to engineers in projects.
When I joined Farfetch, I started by adding to the infrastructure put in place by developers, continuing the documentation where they had stopped. This gained the respect of developers and made the initial documentation immediately findable by everyone that needed it.
How will you make a difference?
There are few University courses in technical communication. Instead, the profession attracts people from many other areas. The backgrounds of the seven students at ISCAP included translation, marketing, journalism, geographic information systems, and veterinary, and their ages were between 26 and 60 years.
SIGDOC/IPCC’88 in Montréal was my first technical communication conference. In the conference banquet, I found myself seated between a former nurse and a former insurance salesman. The nurse said something that I never forgot: ‘Technical writing is just like nursing: all you have to do is care about the user.’
While ‘care about the user’ seems like an obvious thing to do, assuming such a point of view makes all the difference.
Under typical business scenarios, developers will struggle to solve a problem to the point of being happy to get anything to work at all, while quality assurance will try to ensure that at least the major problems are identified and addressed. Writers are often the first to look at new features from the point of view of their users, and wonder:
- Will this feature make sense to the users?
- How will users solve their problems with this feature?
Often you will find that the new feature is less than ideal, perhaps because the feature is too hard to use in practice, or because the feature does not quite solve the user needs. You will strive to explain how the user can use the feature, while advocating for the user needs across the company. The reception to your suggestions will range from the sceptical to the enthusiastic, depending on the company and the team. One company has been known to value these suggestions more than the documentation itself.
It is through our unique point of view that we add value to the company, by doing things that others at the company fail to see.
During the ISCAP course, a side remark reminded the class of the importance of one’s point of view. As the class was considering what would be needed to organize a conference, a student with marketing practice referred to the conference sessions as ‘the entertainment part of the event’. While an attendee will hopefully attend the conference because of the sessions, an event organizer may need to focus on facilities and coffee breaks.
Are you solving the right problem?
Even with the benefit of the right point of view, it is often easier to tackle a larger problem that includes the problem under consideration. In particular, the fixed constraints of the smaller problem that thwart your efforts may become variables in the context of the larger problem.
I heard a story about the two major Portuguese brands of beer at Universidade Católica de Lisboa. Both Sagres and Super Bock saw themselves as beer brewers, fighting for the top spot and for the supremacy of beer over other drinks. Then both companies realized that their market was not selling beer, but quenching thirst. Both companies acquired water and soda brands, thus turning their former archenemies into parts of their own offers. Today, the companies even sell cider and wine.
On the other hand, constraints can be liberating. For example, Hughes Aircraft explored the constraints imposed by typewriters and the separate reproduction of drawings to impose a two-page format that enabled sophisticated negotiation of complex proposals (Tracey et al 1999).
The presentations in technical writing meetups in Lisbon have shown how each company evolves a unique solution to its documentation needs. Each company conducts business in a unique way, influenced by external forces and internal capabilities that shape a unique ecosystem. The balance of forces and capabilities shapes the documentation processes and deliverables of each company.
You will have to figure out what works and does not work in your company and adjust the accepted wisdom as needed. If this seems too much for you as a new writer, remember the advice of Russell Ackoff (1994:107): ‘doing the right thing poorly is much better than doing the wrong thing perfectly’, because improving upon the wrong thing will only make you more wrong.
Or, as Mark Twain said, ‘You’re never wrong to do the right thing’.
How did I pick the right problems?
I will offer two examples where a change of perspective changed the documentation.
The first company that I joined sold a product suite that integrated with a variety of customer systems. Each customer would have a specific architecture and configuration of the product. The documentation fought to explain all the possible variations in an understandable way.
I decided to always include the users in all system diagrams. That decision forced a change of perspective in several parts of the documentation, by forcing writers to explain how each part of the system impacted users. Eventually, we crafted families of drawings that helped us explain how the architectural variations of the product impacted users.
At Farfetch, I was hired to document the public APIs. Within a year, while listening to a CEO presentation, I figured out that the real mission was to document the platform, namely how partners can conduct their business through the services offered as Farfetch APIs.
Will you like the work?
As you work to fill the gap between what the user needs and what the company has created, you will often find yourself in a fuzzy middle-ground. In a sense, your work starts where others have chosen to stop. You may find yourself:
- Explaining business needs to developers, while simultaneously justifying the current technological limitations to the business.
- Explaining how users can use the product while arguing how the product could evolve beyond some limitations.
Your tasks can range from simple and predictable to arbitrarily hard. Phillip Armour (2000) explains the difference in orders of ignorance, that is, how much we ignore about the task.
- 0th Order Ignorance: We know everything about the task, and we just depend on ourselves to do it. For example, English editing of a known author. Usually we can estimate these tasks accurately.
- 1st Order Ignorance: We know how to do the task, but we must ask a few details. For example, document a simple software panel. Usually we can estimate the effort accurately, but calendar days may slide if someone takes time to answer our questions.
- 2nd Order Ignorance: We have a process to follow, which will uncover the details of the work. The real task is discovering what we don’t know. For example, document a deceptively simple software panel, where one of the input fields requires explaining a company process and a decision procedure. We often fail our estimates when the task surprises us.
- 3rd Order Ignorance: We have a problem to solve, but no process to follow. Sometimes, we start with a known process, but we keep being surprised again and again until we conclude that the process is not really working. The key to solve these problems is to understand them better.
How hard can it be? Once upon a time, I was part of a small team of writers that had been working together for ten years. When we started to document a new major release of a product, we made no real progress for two months. Later we realized that the whole company had hit a new wall of complexity. The product required years of work to reach the market.
If you limit yourself to the simpler problems, you may find the work rewarding yet monotonous, but you may still enjoy interacting with others. However, when you learn to do the simple tasks faster, you free up time to tackle the harder problems, and you create the opportunity to grow professionally.
Technical communication can be quite challenging... but then again, nothing quite beats the satisfaction of breaking the back of a hard problem. That moment of inspiration when you look at the problem with a fresh light, and see the new simplicity hiding in the middle of the former complexity. Embrace the challenge, and your work will never be boring.
References
Ackoff, R (1994) The Democratic Corporation. Oxford University Press.
Armour, P (2000) ‘The Five Orders of Ignorance’, Communications of the ACM, 43, 10 17-20. DOI: 10.1145/352183.352194 (accessed 14 April 2020).
Baptista, J (2014) ‘20 Years of Technical Writing at Altitude Software’, Proceedings of ACM ISDOC’14, Lisbon, Portugal. Also available at pxquim.com/publications/2014-05-17-altitude (accessed April 2020).
Baptista, J (2015) ‘Technical Writing for Portuguese Product Companies’, Atas da 15a Conferência da Associação Portuguesa de Sistemas de Informação, Lisbon, Portugal. Also available as pxquim.com/publications/2015-10-02-capsi (accessed April 2020).
Tracey, J and Rugh, D and Starkey, W (1999) ‘Sequential Thematic Organization of Publications: How to Achieve Coherence in Proposals and Reports’, Asterisk Journal of Computer Documentation, 23, 3 4-68. DOI: 10.1145/330595.330597.
This article was originally published in ISTC Communicator, Summer 2020.
