Section 7.2. Basic Information and Community Support

7.2. Basic Information and Community Support

Beginner and intermediate users need education. First, they need to figure out what an open source project does, how mature it is, and whether they have the right skills to use it. Most frequently, these users look at the project's web site, download the software, and then try it out.

Beginner and intermediate users also need help with context. Many of the questions that flood mailing lists have nothing to do with how the open source project functions, but rather concern how it fits into the surrounding environment and what settings are needed to make databases, web servers, and network ports behave properly.

In the subsection that follow, we discuss the most important elements a project should include to help beginner and intermediate users.

7.2.1. Mission Statement

A mission statement or brief description of the project featured or linked to prominently on the home page of a web site is a great help to anyone trying to figure out what the project is all about. Here are some samples and excerpts:

OpenOffice.org

"To create, as a community, the leading international office suite that will run on all major platforms and provide access to all functionality and data through open-component based APIs and an XML-based file format."

Drupal

"A dynamic web site platform which allows an individual or community of users to publish, manage, and organize a variety of content, Drupal integrates many popular features of content management systems, weblogs, collaborative tools, and discussion-based community software into one easy-to-use package."

Babeldoc

"Universal document processor. The open source tool for business-to-business and systems integrators and enterprises wishing to connect data and documents centers. Babeldoc is intended for systems integrators and EAI projects."

7.2.2. Examples and Working Sites

If the project's mission is clear, the next step many users take is to look at working examples. For some software, such as OpenOffice.org, this can mean showing screenshots. For others, such as Drupal, this can mean links to a huge number of other web sites built with the project. For an infrastructure, such as Babeldoc, this can mean a whitepaper on the site that mentions who is using it and for what purpose.

7.2.3. Question-and-Answer Archive

Short of a well-written book, perhaps the single most useful tool to help encourage use of an open source project is an active bulletin board system that the project team scans regularly and that is complemented by a well-maintained FAQ. It is here that beginner and intermediate users can find answers to simple questions about the context in which the software runs. Such a structure tends to allow people to support each other, with simple questions being answered by those with a little knowledge and the leaders of the project team weighing in on the most difficult problems. While an open source project cannot force the creation of a community to use tools such as bulletin boards and FAQs, it can provide them and answer questions on them to get the ball rolling.

Of course, bulletin boards and FAQs are no substitute for a well-written manual or book. But a well-written manual is hard to come by, and FAQs and bulletin boards are easier to maintain by a larger group, which usually makes them the first stop, even when a manual exists.

7.2.4. Documentation

Only the most mature projects have documentation worth the screen it was written on. Most projects have README files and a small amount of documentation aimed at saving those with a high skill level some time searching through the source code. However, frequently these are more like notes to the project's internal members than documentation designed to communicate to newcomers how the software works. For those at the beginner and intermediate levels, the most useful documentation comprises a step-by-step tutorial of how to get a project running so that users can play with it and figure it out through experimentation. We will discuss documentation for more advanced users a bit later in this chapter.

Most of the time, adequate documentation arrives in one of three ways:

• The community supporting a project grows large enough to attract people who feel moved to create documentation as a way to contribute to the project. This generally doesn't happen until projects are on their way to larger-scale adoption.

• Authors and publishers notice a project, prompting the project's leaders or other experts to write books.

• The project leaders make it a priority to write documentation, because they want to encourage adoption or they want to charge for it.

Given that documentation is so rare, it can be one of the easiest ways for a project to distinguish itself as being professional.