Engaging Students in Open Source Documentation Projects

Most students have very limited knowledge of open source programs prior to taking the professional writing class at Purdue University. Therefore, the foremost challenge is to help the students understand the concept of open source programs and cultivate in them some enthusiasm towards open source programs. A suggested pedagogical move is to introduce some open source software programs to the students and assign them a few interesting readings (see the next two sections). The point is to allow the students to put their hands on some alternatives to proprietary software programs that they are already very familiar with. The next step in engaging the students is to direct the students' attention to some great benefits that open source programs will bring to the society and encourage the students to take concrete actions to promote open source programs. One of the actions is to work on various documents on open source programs.

Readings on Open Source and Creative Commons

In addition to texts provided by OSDDP, teachers may want to introduce students to some outside readings on open source and Creative Commons during the first week of working with OSDDP. For example,

• The Open Source Initiative -- Founded by members of the open source community intent on promoting the use of open source within the commercial world, the Open Source Initiative holds the trademark on Open Source. They provide an introduction on the home page, the official definition of Open Source, and a FAQ answering many common questions.
• Creative Commons -- The official site for Creative Commons contains information on the organizations's mission, explanations of Creative Commons licenses, and a weblog which is a good resource for news on Creative Commons from around the web.
• The Cathedral and the Bazaar -- Eric Raymond's seminal text exploring the open source development model may be a technical read at times, but it is the defining piece exploring the benefits of community development through open source licensing. This reading is especially useful to ENGL 421 classes that plan to do documentation development for open source software communities.

Examples of Open Source Software

In order to get more familiar with the concept of open source, encourage students to download and try one of the following applications. Each is easy to install and similar to comparable applications that they already use:

• Mozilla Firefox -- Mozilla's stand alone browser. Its tabbed browsing and other features make it a viable, and arguably, better alternative to IE. Students trying out Firefox may also want to try some of the Mozilla Extensions.
• Mozilla Thunderbird -- Mozilla's stand alone mail client, an alternative to Outlook Express.
• OpenOffice -- This full office suite is the open source version of Sun Microsystems's Star Office and includes word processor, presentation, spreadsheet, database, and HTML WYSIWYG applications comparable to Microsoft Office.

More adventurous students interested in experiencing the Linux Desktop should download Knoppix, a Linux distribution which runs off of cd rom; no installation required. Students will need to obtain the latest ISO tagged EN.iso from one of the Knoppix download mirrors. Once the file has completed downloading, the ISO must be burned to the cd as an image (see the cd burner documentation for more specifics). Then, just restart their computer booting from cd. Since Knoppix does not store anything on the user's computer, students can feel free to try out applications without fear of causing problems with their machine.

Encouraging Research on Open Source Documentation

When technical writing students are involved in open source documentation projects such as reference manuals or how to guides, consider allocating a couple of weeks for outside research. You may need to take a few minutes early on to clarify the difference between "documents" and "documentation" and to describe some common forms of documentation. Use this time to better prepare them to create their first documentation drafts. Assign readings in their text concerning documentation construction, usability, argument, citation styles, working in project groups, etc. Have them draw up documentation plans and create tasks lists. Outside of class, have each group conduct research by

• Reviewing any existing documentation for the open source application they are working with.
• Looking at discussions about the application. Open source communities typically have public mailing lists and forums. Their discussions will contain support requests which may indicate documentation needs, comments about the applications' usability, and specific requests for documentation.
• Finding outside reviews or application community sites. For example, students working with developing Drupal end user documentation should explore opensourcecms. This site not only provides the names of applications similar to Drupal, but it is also has live demos of the applications where they may discover documentation of similar features.
• Reviewing sample documenation guides such as those provided by Red Hat (i.e Red Hat's Getting Started Guide) and other commercially sponsored projects which have polished, professional quality manuals and reference guides.

As they research, have them discuss what they found effective and ineffective in the other documenation they have explored. Suggest that they analyze the different styles of documentation writing they see, the ways in which some make use of graphics, etc. In other words, use this time to make students more effective at rhetorical analysis of documentation.

Small Writing Assignments

As they research open source documentation, students in both 420 and 421 might benefit from small (homework type) assignments in which they summarize their research, evaluate existing documentation, interview a user of open source software and so on.

Using the OSDDP site

Getting Started

When introducing students to the OSDDP site, have them read the project description and FAQs first. After they have a little time to explore surface levels of the site, ask them to create a user account.

Student Privacy/ Confidentiality Concerns

In order to give students some degree of anonymity when publishing online, teachers should recommend that students not use their full name in creating usernames on OSDDP and avoid using their full names in postings on the site. You may also wish to suggest that students not use the ID associated with their Purdue Career Account. Finally, when publishing final versions of documents to the OSDDP Guide, students should always be given the choice of deciding whether to include their name as an author of a text.

Assigning Class Projects to Students

Business Writing vs. Technical Writing Projects

There are currently two OSDDP projects associated with Business Writing (ENGL 420). In the first, students are asked to write a white paper on some aspect of the open source movement. In the second, students perform a feasibility study of open source software for a given client.

Students in Technical Writing (ENGL 421) are asked to create documentation. This goal can also be accomplished in two projects; in the first, students (working in small groups) create a documentation plan, task list, and storyboard. In the second project, students write the actual documentation. You may want to consider asking your students to switch groups at the end of the first project and to write documentation planned by another group.

Claiming Issues within in the OSDDP

Students can assign an available issue to themselves by

1. clicking on the issue that interests them
2. clicking "update issue"
3. using the drop-down menu underneath the "assigned" field. Note that issues can only be assigned to one user.
4. clicking the "Submit" button.

If students have ideas for a project not posted on the site, they can also create a new issue and then assign it to themselves. Students should, however, be encouraged to read through the currrent issues before creating a new one.

Once students have settled on a project, encourage them to:

• Post the names of all students working on an issue (in the case of group projects).
• Add occasional status reports and followups

Making Use of the Threaded Commenting Feature Attached to Each Issue

The threaded comment board attached to each issue can be used a central location for all discourse about an student group project:

• Group members can use it as a central point of communication, discussing their work with each other on the project.
• Teachers and fellow students can provide their feedback there, rather than through email or another other medium.
• Encourage the group responsible for the project to respond to all feedback in order to stimulate dialogue, rather than merely using the comment board as a place for others to merely post feedback.
• The project module is designed for tracking project development. Using the comments provids the means for reviewing individual participation in determining a final grade.

Opportunities for Additional Feedback

Because OSDDP is an open community where members post drafts in progress, feedback on projects no longer need be restricted to the walls of the classroom. Students and teachers as well can provide feedback on projects outside of their class. Instructors might want to make arrangements with other sections to give response as in or out of class assignments or offer to trade response themselves. Regardless, students, teachers, and any member of the OSDDP community is always welcome to provide feedback on any project.

Building the Selection of Available Issues

For additional issues to be available for future classes, teachers are encouraged to post ideas for new topics and projects to OSDDP as they think of them. As students complete projects, teachers should also allow some time for discussion of new topics among their students and have students themselves contribute to the list of available projects. This could be a good thing to schedule on the day that final OSDDP projects are due.

Projects Based on Revising Existing Texts

Since all content in the OSDDP Guide is available under a Creative Commons license, students could evaluate and revise any existing text in the OSDDP Guide. Technical writers could review and conduct usability studies of existing documentation, then create a documentation plan based on their research and analysis. Business writers could research issues covered by posted white papers, reviews, and feasibility reports, and provide updated versions which reflect the changing field of open source and open content.

Evaluating Open Source Documentation Projects

At the end of an open source documentation project, students are encouraged to evaluate the project through a retrospect upon the different steps that they have taken, such as identifying the needs for an open source document, field research on the clients, studying sample documents, drafting and revising the document, and peer reviews. The point is to help the students identify some important steps that are crucial for producing an effective professional document. They are also encouraged to invite potential clients to evaluate the usability of the document that they have produced.

Sample Documentation

ENGL 421 Students may want to look at some examples of good (and bad) documentation to help them create their own.

Software Documentation on the PW site

Open Office Support

Howto: Write Bad Documentation that looks good (ok, so maybe we don't really want to include this, but it's sort of amusing)