Building bridges between product and clients with a team of tech writers
When you think about a software company’s office, perhaps the first image that comes to mind is that of programmers under their hoods, with headphones and dual monitors filled with colorful letters. What you probably don’t realize is that a few chairs away there’s someone who has the word “writer” in the job title — and that the success of the product greatly depends on the result of that person’s work.
Technical writers are responsible for creating and maintaining product documentation. Their goal is to transform the use of intrinsically complex software into a simpler experience through content that explains, educates, and solves problems.
To achieve this goal, the technical writer must combine skills that, for many years, a large part of the market saw as opposite or even self-excluding: they must be able to gather and synthesize complex information and communicate it via text, graphics or video, as a journalist would do; and they must also be able to understand in detail the development and usage of the product, often having to investigate code lines at the same level of depth to which a QA engineer would go, for example.
I arrived at VTEX in 2016 with the goal of helping to improve the platform’s documentation. At that time, not only did I not consider myself a technical writer — I was not even fully aware that this profession existed, which reflected the general panorama of the market, only then beginning to mature its understanding of what a good documenting process meant. Since then, VTEX consolidated this understanding and created the Education team, which today has ten tech writers.
In search of references
It was exactly during the consolidation of this team that we felt the need to seek references and knowledge about the area of software documentation. Some resources proved to be valuable in helping us to fit our work into a framework of best practices that were kind of globally consolidated. Among these resources was the book The Product is Docs, written by the Splunk documentation team, and the Write The Docs community, which since 2013 has held documentation conferences in several cities in the USA, Europe, and Australia.
But as valuable as the discovery of these resources was, we also found out that there was still a lot of space to be explored. In particular, we missed publications that went deeper into the intersection of writing and technology and dealt in more detail with the challenges of someone working at that intersection, which applies not only to technical writers but also to UX writers, instructional designers, content strategists, among other roles in the tech industry.
The Manu<script>
This feeling of void spawned the idea of creating our own publication: in January 2020, we recorded the first interview for The Manu<script>, a biweekly podcast inspired by the desire for knowledge and evolution of the VTEX Education team and produced by two technical writers from that team: Juliana Meyer and myself.
Eight episodes have been published to date, and each has delved into a specific aspect of writing for technology while opening up new universes that we had never even considered. Among the interviewees, we had: Tom Johnson, a technical writer at Amazon whose blog I’d Rather Be Writing is a reference in the area; Mark Baker, author of the book Every Page is Page One; Mary K. Nielsen, content strategist at Mailchimp; and Torrey Podmajersky, UX writer at Google and author of the bestseller Strategic Writing for UX.
Each interview reinforces how complex the writing job in the technology market can be and also how impactful that job can be on the outcome for companies that really care about it.
Perhaps one of the interviewees who made this impact most clear was Christopher Gales, Senior Director of Documentation at Splunk. He leads a team of 45 people, including writers, editors, and technical writing managers. In his interview for The Manu<script>, Gales stresses the importance of seeing the professionals responsible for documentation as part of the product team, taking up a role that connects Engineering, Product Management, Design, and Consumer Support.
“Since the company’s first product leader,” says Gales, “we knew that in order for our customers to adopt the product and be successful with it, at least some of the content consumed by them would need to be built by professional writers.” And to be effective, he says, this must happen from the very beginning of the product development — technical writers must be in the room since the first meeting.
At Splunk, as well as at VTEX or any other software company, there is knowledge about the product being produced every day. When this knowledge is repressed rather than communicated, it becomes a barrier to the effective use of the product and, consequently, to the company’s commercial success. Technical writers are the professionals capable of understanding, organizing, and transmitting this knowledge, transforming this barrier into a bridge between product and customers.
I hope more publications such as The Manu<script> are created to multiply this bridge and open new paths for those who work or wish to work in the world of technical writing.
Listen to The Manu<script> on your favorite platform:
