What makes good technical documentation? First of all, a good writer! What sets tech writers apart from others, though, is more than a strong grasp of technical language or the content demanded by technology providers. From manuals and guides to product strings and white papers, tech writing is defined by its demand for accuracy.
One of the most fundamental skills for achieving that accuracy is the ability to gain a strong grasp of a document’s subject matter, whether or not it has been effectively defined by a client. Often this is not possible working from source materials or provisional documentation alone without also interacting firsthand with the people who have developed these. Sadly, many content providers make do on the willingness of clients to deal with them remotely, generating mediocre material that misses key opportunities to add value to the products they stand for.
When it comes to boosting a technical document’s value, going on-site with a client is a chance to ask the right questions, feel out pain points, and assess the considerations that technical experts are likely to overlook. Working with the backing of strong corporate resources makes this possible in ways that it otherwise would not be, founded on the certainty of good-faith conduct on both sides.
Among our clients at CSOFT, several cases illustrate how impactful a face-to-face meeting with stakeholders or a visit to a production site can be.
Meeting a Global NGO in Sudan
After months of work documenting an online system for organizing humanitarian aid at a global NGO, CSOFT had plenty of unresolved questions about the processes involved. With offices in more than 80 countries, several complex aid models, and a workflow spanning multiple departments, it was clear that the organization needed our document to account for a long list of user roles and responsibilities. As planned with the client, it was time to move beyond preliminary drafting and actually visit one of the countries where this system was being put to use – namely Sudan.
Members of CSOFT’s global communications team working onsite in Sudan
There, CSOFT’s writers were able to see past the clean compartmentalization of the online system and witness the on-the-ground problems it was built to help solve. Rather than misunderstanding, our initial questions reflected insight into the problems the office faced, with limited staff and resources and challenges completely unique to the environment in Sudan. We quickly discovered that our guide needed to help users navigate the system while taking into account those variables, rather than simply teach them to use it effectively. Their roles were liable to shift, and so could their approach to the system, as long as the instructions were clear enough.
Finding a Focus When Experts Disagree
When a major international power solutions provider sought CSOFT’s services for a white paper comparing two standard variations of a common industrial device, our first steps involved reading through decades of competing research on their respective performance qualities. The technology was challenging on its own, and the company’s preference as a manufacturer of both variants proved difficult to determine from its own materials. Calls with senior technical experts helped to illuminate key considerations, but the question remained: Which of the two models should be promoted for wider adoption? At CSOFT’s request, a visit to nearby production facilities and meetings with senior engineers were arranged.
On site, CSOFT’s writers were able to examine deconstructed samples for each device variant, discovering relationships between scientific principle and practical engineering at the parts level. With physical models to refer to, discussions with experts confirmed many of our tentative ideas while redirecting others. Gradually, we discovered that these experts all had their own preferences between the two device variants, with no one consensus among them. Our final takeaway for the direction of the paper, unexpectedly, was that both had their respective advantages; as the client agreed, it needed to provide was a better basis for choosing between them on a by-case basis.
Documenting an Intangible Technology
A major domestic telecommunications equipment provider in China needed help improving technical documentation to support its growing global market reach. After working out issues of style and tone, the next task was to evaluate the quality of its technical information. This required a strong understanding of telecommunications technology.
When trying to understand a new system, it helps being able to see all the parts of that system in the same place. This technology presented a unique challenge: when a system is made up of numerous components spread out over a whole city – including the devices of residents constantly on the move – it becomes persistently difficult to keep all dimensions of its underlying technology in focus.
To help, the client arranged a 30-minute visit to its equipment testing room, where a complete miniature telecommunications network had been set up. With each logical component of the network on display and the client’s guidance throughout the session, CSOFT’s team came out of that short session ready to address the client’s content needs.
Key Takeaways
Many of the challenges technical documentation writers face serve to demonstrate why their work is so important. Reading through provisional materials that technology providers create for their products is an essential part of researching new projects, but is likely to generate misconceptions about the subject matter due to the existing content’s lack of clarity.
In almost any case, the best way writers can ensure quality and accuracy in technical documentation is to seek opportunities to engage clients and their technologies at close proximity. Many problems are human problems, as CSOFT learned repeatedly in Sudan. Others occur in too many dimensions for technical experts to communicate in language alone. Nevertheless, these challenges are highly similar in terms of their solutions.
With a strong foundation for mutual trust and experienced writers who observe best practices, a visit to production facilities or a sit-down meeting with engineers is often all it takes to enhance the reach and value of a much-needed piece of technical writing.
Learn more about CSOFT’s work delivering technical content across borders!
[dqr_code size="120" bgcolor="#fff"]