January 2010

"When you ask someone to create a manual, be sure they know who and what it's for. Be sure they know that the goal is not simply To Accurately Document The Thing, but to Help The User Kick Ass."

Kathy Sierra

This article describes the importance of user assistance to the success of open source projects and offers some suggestions on fostering community contributions to open source user assistance. The term "user assistance" encompasses all the ways that users get help in figuring out how to use a product, spanning the traditional categories of both documentation and support. User assistance provides opportunities for participation by community members who are not software developers. This in turn relieves the burden on developers for filling these roles while broadening the community. Projects should support the differing motivations of members in these roles while providing leadership and direction, removing barriers to contribution, and engaging in concerted efforts. Licensing for open source documentation should likewise be open, to support user freedom and foster community collaboration. Leaders in open source user assistance need to share ideas across projects in order to improve their offerings.

Importance of User Assistance

In the fall of 2009, the poor state of documentation for Linux and for open source projects in general became a trending topic in blog posts and online magazine articles. Writers lamented the lack of documentation relevant to user's need, the surplus of disparate and outdated information, the lack of responsiveness of developers to user problems, and the poor attitude of developers toward documentation. However, few offered much in the way of constructive advice, with the notable exception of Bruce Byfield's article on Information sources for documenting free software, in Linux Magazine.

This article describes the importance of user assistance to the success of open source projects, and offers some suggestions on fostering community contributions to open source user assistance.

Creating good user assistance is important to open source projects for multiple reasons:

  • it helps users become effective in using the product, which spurs adoption of the software

  • people who might not otherwise be able to contribute to the project can help with user assistance, which expands and fosters the community around the project

  • it can free developers from dealing with support issues

  • user assistance efforts can provide filtered feedback on areas for product improvement

User Assistance is More than Manuals

The term “documentation” tends to limit thinking to traditional manuals and perhaps on line help.

The term “user assistance” encompasses all the ways that users get help in figuring out how to use a product. User assistance can include:

  • text embedded in the software, including field labels, window titles, and error messages (for end users), and comments in the code (for developers)

  • online documentation accessed from within the application

  • formal manuals or books

  • smaller standalone documents such as how-tos, FAQs, manual pages, or tutorials

  • video tutorials or demos

  • mailing list or forum questions and answers

  • live chat with experts or other users

These different forms of user assistance vary in their degree of formality, granularity, searchability, and responsiveness. Information in any of the categories listed can target a variety of audiences such as new users, expert users, programmers, or administrators. Most can be delivered through a variety of media, including blogs, wikis, traditional websites, or paper documents.

Users turn to different forms of assistance at different times in their usage of a product. Using Google to search forum postings is not a substitute for other forms of user assistance; rather it is a point in a continuum of user assistance. It can be useful to think of a user's experience of a software product as a conversation that the user engages with the product, the community, and various artifacts. Over time, ideally, the user not only seeks answers to questions, but also offers information that he or she discovers. Anne Gentle discusses this process in Conversation and Community: The Social Web for Documentation. While her book is aimed at professional technical writers rather than open source community members, it can be helpful in seeing how social media can feed into and gain from traditional documentation.

Many Roles can Contribute

Open source projects are typically started by programmers to “scratch their own itch.” Programmers have the skills to create the code, but may or may not have appropriate skills to grow a community or create user-focused documentation. Even if they have the skills, those other activities may not be the most effective use of their time. The responsibility of a project leader is to find other participants who do have the appropriate skills and to set them loose. The need for user assistance is an opportunity for involving and growing the project's community. Creating user assistance can be a way for people who are new to the project or otherwise not directly involved in programming to contribute significant value.

While the project's programmers have in-depth technical knowledge of the product, they are often not the best people to write the user assistance. This has little to do with writing skills, and a great deal to do with perspective. It can be difficult for someone with an intimate knowledge of the technical details of the product to adopt the perspective of someone who has never seen it before. This holds true even for software libraries whose audience is other programmers. The programmer using a library's application programming interface (API) may lack the conceptual framework that is “like water to a fish” for the programmer who wrote the library. It is often more useful for someone other than the original programmer to write the user assistance, using the original programmer as a “subject matter expert” for technical details.

An important role in creating large-scale documentation is reviewers to review drafts. Unlike programs, documents cannot be automatically checked beyond the rudimentary checking provided by spelling-checkers. Human reviewers are needed for copy-editing and proofreading, to ensure that the document follows the conventions of the language, and for technical review, to ensure that it is technically correct. Reviewing can be an entry-level role for community members who don't yet feel sufficiently knowledgeable to create documentation.

The problem for some open source projects is not that there is too little information, but that there is too much, it is too widely or unevenly distributed, and it is too poorly coordinated or maintained. In such cases, curators are needed to discover and sift through the information that exists, catalog it, evaluate it, and provide pointers in a centralized location. This type of inventory can uncover areas that need updating and gaps where information is needed but does not yet exist. These needs can then feed the task list for writers and editors.

Another role can be for rewriters to repurpose and remix existing content in more accessible forms or for different contexts. For example, a mailing list thread for troubleshooting a problem contains back-and-forth and extraneous information that, for later readers, interfere with extracting the useful nuggets. A community member could abstract that thread into a troubleshooting topic on a wiki. For this to happen, someone must take on the task of watching for candidate topics on the mailing list. As an example of remixing, a volunteer with an educational background could create variants of existing documents for grade-school children, with supplementary information for educators.

Community and Personal Growth are Motivators

Unlike programmers, writers looking to “scratch their own itch” tend to find more expressive outlets than technical documentation, such as novels or poetry. In Why do people write free documentation? Results of a survey, Andy Oram found that the two highest-rated motivations for writing open source documentation were community-building and personal growth. Reputation-building and enjoyment of writing were ranked relatively low as motivations.

It may be more motivating for writers to know that their work is being used and appreciated by the community than to get personal kudos for their work. Some automated tools exist to provide such information, such as website traffic logs to find which pages are most often read, and page ratings (supported by some web content management systems) to find which topics are most useful to users. This information can be shared with writers, and used to prioritize updates. An often-read but poorly-rated page should get more attention than a highly-rated but little-read one.

The motivation of personal growth is more intrinsic: people often write about a topic in order to learn it more thoroughly themselves. What project organizers can do to support this motivation is to tolerate and even encourage user assistance contributors who have less than expert technical skills. While existing experts may be too busy with other concerns to write documentation, other community members can become experts through the process of documenting. Alternatively, an expert can become a better writer through the practice of writing, especially when given constructive feedback from reviewers.

User Assistance Requires Leadership

In order to create a growing base of users and a thriving community, user assistance cannot be an ad hoc effort. User assistance encompasses both “support” and “documentation” as traditionally conceived. It may be practical to separate support and documentation activities, but close coordination between the two areas leads to better experiences for users. Support channels are a source of actual user questions that can become new documentation topics, while existing documentation can be a resource for support contributors.

Projects that are bigger than a handful of developers need leaders specifically responsible for support and documentation efforts. A support leader helps ensure that user questions are answered in a timely manner and that flame wars and spam are contained. A documentation leader coordinates efforts to plan, create, and maintain documentation. This person may actively participate in creating and editing documentation, or may focus on clarifying the community's vision for the documentation and guiding contributors.

For projects that have a corporate sponsor, the community may expect the sponsor to create the documentation. Whether this expectation arises may depend on the dynamics of the larger project. It is more likely to occur if the open source product was created primarily by the sponsor and released as open source, and less likely if the project evolved first. In the former case, the sponsor may fund development of primary documentation, while accepting community contributions. Such contributions are likely to be granular, such as specific configuration how-tos or troubleshooting topics. Or, responsibility for documentation may be shared between the sponsor and the community. According to Jean Hollis Weber, Documentation Co-Lead for OpenOffice.org, the project's corporate sponsor, Sun Microsystems, maintains the online help that is accessible within the product, while the community project creates and maintains end-user manuals. The community documentation project also handles documents aimed at programmers and system administrators, but Weber reports that much of that content is contributed by Sun employees.

Lowering Barriers Enables Contribution

Community involvement in user assistance increases if barriers to involvement are kept low. User assistance activities should be advertised areas for involvement on the project's website, with a clear means of contacting leaders and discovering needed tasks.

Designating leaders for user assistance efforts does not absolve developers of involvement in these activities, but shifts it. Rather than directly providing support and writing documentation, developers need to be responsive to contributors in these areas, supporting them and answering their questions. For example, providing regular binary builds not only supports end-users, it also helps community members who are trying to help end-users. It should not be necessary to check out the source tree from version control and build the software from scratch just to contribute to documentation.

The technology used in documentation efforts can be a barrier if the tools require significant training for community members. Historically, many open source projects have used open but arcane documentation formats such as LaTeX or DocBook XML, which are unfamiliar to non-programmers. Some projects are now turning to less challenging formats. For example, the documentation for the Python programming language is now written in reStructured Text, a wiki-like plain-text mark-up syntax, instead of LaTeX. The Gnome Documentation Project is starting to use Mallard, a much-simplified, topic-oriented alternative to DocBook.

The advent of wikis has made it possible to open a project's documentation to contributions by just about anyone. However, wikis bring their own host of issues. It is not reasonable to assume that creating a wiki will lead to documentation magically being written, or that it will automatically be comprehensive, well-organized, or easily searchable. A wiki is simply a platform and a documentation effort that uses a wiki still requires management at the social level. A wiki is inherently unstructured, and so a structure must be imposed on it to support users in finding information. A defined structure also helps writers in knowing where to plug in new pieces of information that they want to contribute.

A project that provides a purpose-built, wiki-based platform for open source documentation is FLOSS Manuals. The site has been customized to support collaborative creation of comprehensive texts, with a WYSIWYG HTML editor, an embedded IRC widget, and document structuring tools. Documents can be rendered as HTML or PDF, and can be embedded in another website or uploaded to a print-on-demand service. While the current site is a one-off instance, efforts are underway to reimplement the same features and more as a new open source web application called “Booki” for “book wiki”. The project welcomes any documentation effort that discusses open source software, whether for a single application or spanning multiple applications.

Concerted Efforts Bring Ongoing Results

Open source programmers have long used “sprints” or “hackfests” as a way to boost a project by gathering contributors for a brief but concentrated effort. The same principle applies to documentation as well as to code. The FLOSS Manuals project has honed and refined the idea of a “book sprint”, originally created by Tomas Krag to write Wireless Networking in the Developing World. A set of people who are interested in creating a book on a particular topic gather in a given place for a short period, typically two to five days. At the end of the sprint, the book is published to the FLOSS Manuals site. Holding a book sprint is not a requirement for creating a book on the FLOSS Manuals site, but experience has shown that books that were created in books sprints have the greatest level of ongoing participation.

Dave Greenberg is a co-founder of the CiviCRM project who participated in a FLOSS Manuals book sprint to create a book, Understanding CiviCRM, to supplement existing CiviCRM documentation. He says “The online doc (on the wiki) is procedurally oriented – lots of how-to's, but we got feedback that ... it didn't provide evaluators and new users with the big picture. 'Is this software right for my organization/client?' 'What can I do with it?' etc. … we wanted the book to help decision makers and consultants who were evaluating software solutions to have some concrete examples of who, how and what.” He reports that CiviCRM is planning to hold two more sprints in 2010 to update the first book and to write another with conceptual information for developers.

In contrast to short-term sprints, another strategy for concerted documentation effort was a “documentation marathon” to document the NumPy API, organized by Joe Harrington over the summers of 2008 and 2009. Participants were recruited through community mailing lists, and rewarded with T-shirts for significant levels of contribution. These efforts resulted in 78% of the API categories reaching the goal of having complete content ready for review.

The lesson for any open source documentation project is that setting and achieving a significant goal can have lasting effects on the project.

Open Source Software Needs Open Documentation

The principles that underlie free and open source software also apply to documentation. Users of open source software need to be able to read, study, modify, and copy the documentation of that software. While there is a place in the open source ecosystem for traditionally published, restrictively copyrighted books (even as publishers become more accepting of open licenses), the primary documentation for an open source product needs to be as open as the software itself. Restrictive licensing of documentation inhibits contributions to, collaboration on, and translation of that documentation. Open source projects where the official documentation is restrictively licensed may find users creating their own, unofficial, open-licensed documentation.

Like other issues related to open source licensing, the question of which license to use for open documentation is a matter of debate, with arguments for and against various specific licenses. Dual-licensing may be a reasonable choice in order to satisfy competing requirements such as compatibility with distribution guidelines and other licenses. It is logical for documentation that is distributed along with software to use the same license as that software, or a compatible license. For documentation that is distributed separately from the software, more flexibility is possible. Where documentation is created collaboratively, use of a specific license should be a condition for accepting contributions.

Good User Assistance is Achievable

In response to the blogs and articles about poor open source documentation, commenters cited examples of projects whose documentation they consider helpful, including OpenOffice.org, GnuCash, PHP, MySQL, Gnome, Ubuntu, OpenBSD, and OpenSolaris, which indicates that these projects are succeeding at helping at least some users “kick ass.” The issues related to producing helpful user assistance are not unique to open source projects. Proprietary software companies face them as well: some proprietary software user assistance is excellent, and a large amount of it is poor. Employees of proprietary software companies share best practices through organizations such as the Society for Technical Communication and the Association of Support Professionals. Community members involved in open source projects can learn directly from these organizations, but also can and should share with and learn about best practices from each other. In that spirit, June 2009 saw the first-ever conference on Writing Open Source for open source documentation leaders to gather and share ideas. That conference resulted in a website that promotes collaborative discussion on topics ranging from writing to technology and community building. Good user assistance is achievable, but requires concerted effort, strong leadership, and a focus on user needs that is strengthened through dialogue and collaboration with user communities.


Share this article:

Cite this article:

Rate This Content: 
1 votes have been cast, with an average score of 5 stars