Features

Implications for Technical Communication in the Rise of International Open Source Software Use

May 13, 2016

By Clint Lanier | Senior Member

Open source software (OSS) is often defined as software that is both made available to the public without cost and made available for the public to copy and to modify. This openness means the size of an OSS project can range from small and one-time software applications, such as various OSS apps and plugins, to large, ongoing endeavors, such as the Linux operating system or the Mozilla Firefox Web browser.

The collaborative and open nature of OSS means contributors to OSS projects generally span the entire globe. In fact, the Red Hat/Georgia Tech Open Source Index Project noted in 2009 that the three countries with the most OSS activity at that time were (in order) China, Japan, and Brazil (Lanier, 2011). This international aspect is important because use of OSS systems by professional organizations has risen 36% over the past decade. As a survey of professionals in the IT industry by the OSS logistics firm Black Duck Software notes, “Seventy-eight percent of respondents said their companies run part or all of its operations on OSS and 66 percent said their company creates software for customers built on open source.”

These numbers suggest current and future software activity will be dominated by collaborative actions taking place in global contexts and involving participants from a variety of cultures. For technical writers, the implications are enormous and being ready for them will be central to professional success over time.

Traditional Documentation

From a technical communication perspective, one of the biggest issues surrounding international OSS adoption and use is a corresponding lack of quality—or even complete—documentation for software products. In fact, according to a 2013 article by Linux Insider, documentation ranks as one of the foremost complaints associated with OSS use (Germain, 2013). The reason for a lack of documentation quality seems to be that the individuals developing the software see little worth in pursuing aspects not concerned with coding. This perspective, in fact, tends to dominate OSS projects—many of which are driven by volunteer programmers working in their spare time.

Further complicating this situation is the fact that many contributors to OSS projects are potentially from different cultures and speak English as their second or maybe third language (if at all). Because OSS most often uses English as the central language contributors/developers use to interact, the potential for “bad” documentation is enhanced exponentially. There is, therefore, an urgent need for technical communication professionals to step into this void and contribute to the documentation efforts of international OSS projects. In fact, a failure to do so can markedly affect how widely used an effective OSS product might be on both domestic and international levels. Technical communicators can adopt certain strategies to address this documentation need effectively in global contexts.

Strategy 1: Creating and Translating End-User Documentation

The most obvious task for technical communicators is creating documentation for a range of international end users. While international use of OSS is growing, there remains a lack of effective documentation for users from different cultures. Here I am not speaking about large, well-coordinated and old projects like Mozilla or Linux, but rather smaller, more recent projects—many of which have the potential to affect practices on a global scale.

Another related task would involve coordinating or facilitating the translation of existing documentation and of the documentation being developed by technical communicators. As coordinating the translation of documentation (e.g., locating and working with a translator) is a process often coordinated by technical communicators, these individuals would seem ideally poised to oversee such practices for globally distributed OSS projects. This situation can be true for translating other languages into English (e.g., Spanish to English) or translating English-language documentation into other languages (e.g., English into Russian). When it comes to OSS projects, the need to coordinate both kinds of translation is great.

Strategy 2: Editing Existing Documentation

English-language documentation written by nonnative English speakers might contain problematic errors—particularly if the individuals creating the documentation are doing it as an afterthought, while developing the product, or in haste. As a result, such documentation could contain many basic errors in grammar, structure, or spelling. Such errors could, at a minimum, undercut the credibility of OSS products associated with such documentation; in a worst-case scenario, they could be so bad that they affect the use of—or impede the effective use of—the related software. In these cases, technical communication professionals can help by editing such documentation to reduce errors and enhance the usability of both the documentation and the related OSS product. Moreover, editing can help with the later translation of such documents by reducing the need for translators to query an author to request clarification on what idea the writer wishes to convey in a particular problematic passage.

Strategy 3: Developing Multiple Types of Deliverables

In terms of deliverables, OSS documentation, if it exists, is often available in only limited formats. Sometimes it could be a PDF file downloaded with the software; in other cases, it might be in the form of an FAQ sheet someone has set on the development website. And in certain cases, if the OSS effort is mature and very well coordinated, the software will include a linked set of context-sensitive help files designed to facilitate effective use. Rarely, however, especially in the smaller projects, have I seen all three.

In the case of Strategy 3, technical communicators might be asked to help implement their single-sourcing expertise to deliver information in multiple formats (e.g., PDF-based documentation, online FAQs, and links embedded into the software itself). In truth, end users might need a variety of documentation types to help them successfully install, effectively run, and generally operate an OSS product. Therefore, technical communicators could convert existing documentation to multiple formats, such as embedded help systems or online docs. Technical communicators might also create useful Web-based tutorials (videos or text), comprehensive FAQs, or simple print-and-downloadable user guides. Doing so requires one to understand the needs of an international audience and the conditions under which the members of such an audience would be accessing and using such software (a classic need for understanding user experience design). To address such global needs, technical communicators must research audiences from different countries and cultures in order to develop the approaches needed to convey information and instructions effectively to such users.

Other Forms of User Assistance

The other area that might have implications for technical communicators concerns nontraditional documentation methods, specifically user forums. There is a growing use of peer-to-peer (P2P) user forums as support mechanisms for OSS. In fact, these forums seem to be the de facto user support—a form of hybrid documentation—used for a number of OSS projects, where they are of obvious importance to OSS developers. It may be that such forums have become a standard method for providing support. It certainly is more convenient when communities of users can answer each other’s questions rather than relying on the developers.

The mechanisms for making forums available, such as the leading forum software, phpBB, are also usually free and easily created and integrated into projects. In fact, GitHub, the leading hub of OSS projects typically used as the repository for projects by developers, has a forum/messaging capability already built into it (see “Further Resources” for helpful information about forums).

It has been suggested that technical communicators could carve out new roles for themselves as moderators of such forums. After all, such forums may represent an ideal type of user assistance as they answer users’ questions that documentation writers may have never thought of. (In essence, they are a kind of customizable help function.) Within this context, technical communicators could navigate such forums to help users find the appropriate answers for their questions. Technical communicators could also review such forums with the goal of aggregating correct information for the community, and (provided they have the proper access) these technical communicators could correct posts, either language or technical information, created by other users.

In international contexts so common to OSS, technical communicators will need to be sensitive to cultural communication differences (discussed more in the next section). In sum, they must be able to use online forums as a mechanism to communicate effectively with people who could have limited ability to communicate in or read English. Additionally, technical communicators would have to be aware of—and address—a range of variables (from culture and language to economy and infrastructure) that could affect when and how individuals from other cultures and in other nations use online forums to ask questions and obtain answers or instructions.

Strategies for Working on International Aspects of OSS

As global OSS use continues to increase, it stands to reason that technical communicators will likely be involved in some of these projects. The question becomes, what can they do to work effectively in such contexts? While success will likely be based on a case-by-case situation, there are three general strategies that can be of help in the context of most international OSS projects.

Strategy 1: Understand Cultural Differences

Because many users of OSS will likely be from nations other than the United States, technical communicators will need to have an initial understanding of cultural differences, especially in the way people communicate online. In some cultures, for example, individuals might expect very detailed and explicit instruction; in others, users might need a thorough explanations of abstract concepts before they fully understand a point or direction. In some cases, users might require much less information and only rely on the abstract concept to guide them. While our first instinct is to attribute these differences to user knowledge or level of experience, there is evidence that they may in fact be related to the different cultures that people come from. These cultures have different ways of communicating that must be understood. For the technical communicator, the key is to research the cultures for which one might be generating documentation, learn the preferred communication preferences of individuals in that culture, and then create documentation that meets those expectations. It is a case of “knowledge is power,” and the more the technical communicator knows about a given cultural audience, the more empowered the technical communicator will be to help meet the information-seeking needs of that audience.

Strategy 2: Use Precise Language

To better assist international users, there will also be a greater need to practice more precise writing in OSS documentation. This writing should be drawn from the instruction given in the practice of Simplified Technical English (STE). The practice of STE prefers language for technical documentation that (among other things) uses few synonyms and uses words that are easily translatable without confusion. The classic example would be to say that doing something is “difficult” instead of saying it is “hard” because the word “hard” could describe the density of an object, not the complexity of a task. Thus, the more precise word “difficult” lends to more accessible communication for users with limited English skills (see “Further Resources” for helpful information about culture and communication). For technical communicators working on international OSS projects, the key to success is to familiarize themselves with these practices in advance of working on such projects.

Strategy 3: Garner Support from Organization

Technical communicators will likely also need the support of their employers to contribute to OSS projects, as OSS work is often performed by dedicated volunteers and for free. This situation might not be so difficult or far-fetched. As noted, a study by Black Duck Software found 64% of respondents said their companies participate in OSS projects already (mainly because their companies build on the software for their own purposes). Whether they are already contributing to the documentation or user-assistance efforts is unclear. It should be a matter of practice, however, that when the software project is improved, it is done so not only through effective programming, but also through effective user assistance—a process that would benefit the international population of users.

These are only a few items technical communicators should consider in light of the global spread of OSS use. One thing is for sure, as more nations gain Internet access and more cultures interact in the global economy, the need for and the use of OSS products will only increase. For technical communicators, this factor will likely mean increased work with international colleagues and clients who rely on OSS products to interact and engage in various business-related activities. By understanding some of the dynamics of documentation practices associated with international OSS projects, technical communicators can better ensure their success in such contexts.

Further Resources

For more information about OSS and its history, see the following sources:

For more information about forum software, its availability and use in OSS projects, see the following:

For more information about culture and communication, see the following:

For more information about precise language use, see the following:

References

Black Duck Software. Seventy-Eight Percent of Companies Run on Open Source, Yet Many Lack Formal Policies to Manage Legal, Operational, and Security Risk. Retrieved 16 April 2015 from www.blackducksoftware.com/news/releases/seventy-eight-percent-companies-run-open-source-yet-many-lack-formal-policies-manage.

Germain, Jack M. FOSS Devs’ Biggest Complaints: Documentation and Licensing. Linux Insider. Retrieved 26 August 2013 from www.linuxinsider.com/story/78825.html.

Lanier, Clinton R. 2011. Open Source Software Peer-to-Peer Forums and Culture: A Preliminary Investigation of Global Participation in User Assistance. Journal of Technical Writing and Communication 41.4: 347–366.

CLINTON R. LAINER (clanier@nmsu.edu) is an Assistant Professor at New Mexico State University. Before pursuing his PhD in rhetoric and professional communication, he was an information developer for IBM and a technical editor for the Army Research Laboratory. He continues to consult for private and public organizations.