Empathy, prioritization, integration, and dissemination: the four drivers o...

Although many technology companies now recognize the importance of good documentation for the success of their digital products, we still find a lot of inertia in the market on this front.

In practice, all companies want the concrete results that quality technical documentation provides, no doubt about it. But are they ready to invest the effort and recognize that this journey requires, above all, commitment?

With a small team of tech writers and a long history of products developed without proper documentation, our VTEX team felt the pains of accelerated growth without proper support for knowledge scalability. Thus, we have learned from experience that the challenge of producing top-notch technical documentation is as great as its important role in the future of the company.

It has been a hard yet very rewarding journey! Drawing on this journey, we want to share some insights that were key for structuring our documentation, which can be grouped into four major pillars: empathy, prioritization, integration, and dissemination.

Empathy when writing functional documentation

The art of communication is based on the ability to transmit messages from a sender to a receiver, without any noises hindering information exchange. If you, as the sender, do not understand the message you want to convey and the receiver who will be the recipient, how do you expect to communicate successfully?

Without proper a understanding of the product and its users, a technology company is unlikely to overcome the documentation obstacle as it grows.

As cliché as it may sound, empathy is a key point that is often overlooked in the documentation journey. VTEX was no different! There have been many times when we have published documentation without reaping the desired results, precisely because we wrote without properly empathizing with our clients.

We learned our lesson: only those who actually take the time to be empathetic to understand all the product use cases beyond a single point of view produce functional documentation. Empathy is a daily exercise that helps us, even today, in gaining a deep understanding of the product and its users, as well as in identifying which tasks should be prioritized based on the impact they will have on the company’s development.

Prioritizing for creating impact

When we take the first step in a long journey, it is common to think more about the final destination than about the starting point.

Following this logic, we place high expectations on delivering quick value to users, often ignoring the necessary effort that goes into building and executing a backlog that is relevant to readers of future documentation.

A common mistake for VTEX was trying to plan a backlog that addressed the extensive challenge before us. Not surprisingly, we ended up having little impact and getting lost among the many tasks that we had.

But beware, a big extensive backlog does not necessarily represent the major documentation gaps in a product. Often, it is just a result of the multiple demands (with varying levels of urgency) that come from all sides at this early stage of the journey.

Abstaining from passively accepting all documentation demands was one of the key turning points for our team. At that time, we independently detected where the greatest opportunities for impact were, identified which tasks reflected them, and, finally, used the documentation as a tool to generate concrete results in the company’s knowledge production.

Integration for scaling efforts

If you only worry about filling gaps, it is unlikely that you will ever be done! I would say that is the main lesson we learned.

The product changes daily. Therefore, we are constantly getting new demands. How can we keep up with the fast pace of documentation? With a small team of tech writers and a huge challenge before us, we put our bets on having well-integrated processes with the development team to scale our efforts, which translated into:

• Collaborative documentation initiatives such as docathons — task force marathons in which developers engaged with documentation come together to update older documentation or create new documentation from scratch.
• Converging workflows between tech writers and developers, ensuring that new features and updates are always identified and documented prior to deployment.
• Standardization of new documentation with templates, like this README that we adopted as a starting point for VTEX React apps. Using a good documentation template helps developers writing independently during the workflow and, consequently, the subsequent review by technical writers.

Investing in integrating with the development team and in their understanding of the importance of documentation accelerates results and increases impact. In the last two years, we have seen a real revolution in VTEX documentation, mainly from the inclusion of tech writers in the development team’s day-to-day process and their commitment to giving new meaning to the documentation culture and the product “Definition of Done” steps. What was once neglected is now a clear rule: no documentation, no deployment.

Dissemination for ensuring consistency

How could people seek support in documentation they do not know exists?

In the race to deliver value to the product users, we only worry about the amount of written documentation and forget to communicate what has already been published, that is, what is already accessible for searching.

For many years, the VTEX team went on to produce new documentation, but without thinking about the importance of disseminating it. The result, which is more understandable today, was bitter for us at the time, few accesses to content that had required great effort from us.

We learned the following lesson from that mistake: disseminating new documentation, or even important updates to old documentation, generates:

• Transparency about the work of tech writers.
• Accesses to documentation already published.
• Valuable feedback from users for improving documentation.

Based on this, we invested in clear communication formats, such as release notes, and in broad interaction channels, such as Slack. It was not long before we reaped the fertile results listed above when clients started actually consuming our documentation.

Regardless of the chosen format and channel, the most important thing is not to fall into the pitfall of publishing without further dissemination. Remember, new documentation basically works like a new digital company product — if no one knows about it, no one uses it!

Embracing the continuous journey of documentation

The first step in any new chapter in life is always challenging. The insecurity of not being able to move forward will linger until we get up and risk taking the first step.

As expected, VTEX took a risk. We committed to changing our documentation paradigm and invested heavily in making a change by following our principles: “Trust to be trusted,” “Build for community,” and “Be bold.” Now that we are satisfied with every step we have taken so far, we share the main lessons we learned through our ongoing journey.

It is ongoing because it is a path that keeps going. The finish line of this marathon is an illusion: the more you write, the farther it gets. And that is OK!

Digital products are constantly evolving and, consequently, so is their documentation. Change is the only certainty. It is a continuous effort. Make peace with uncertainty and celebrate it — the infinite documentation journey is just a reflection of a company’s accelerated growth!

A Tech Writer is responsible for all technical documentation of a company’s digital products. Are you interested in this career? Click here to see openings at VTEX and join our team!

Written by Beatriz Guerreiro