This is a read-only archive. Find the latest Linux articles, documentation, and answers at the new Linux.com!

Linux.com

Feature: Collaboration

Using a wiki for FOSS application documentation

By Drew Ames on May 09, 2008 (9:00:00 AM)

Share    Print    Comments   

For a lot of programmers, writing an application is fun, but writing its manual is not. Adding new features, refining the product, and responding to users' input are all more rewarding than writing instructions on how to use the software. However, good documentation is necessary to have happy, informed users who can contribute meaningfully to future development. A few months ago, Gilbert Ashley, the author of src2pkg (Slackware's "magic package maker") invited me and two other people to help him manage the user documentation for his program. The process we used to create the src2pkg wiki may be a useful example for other free and open source software (FOSS) application developers.

Software documentation projects differ in scope, scale, and goals, but all must address a few basic items. Getting a project like this off on the right foot requires some planning and a few decisions to determine

  • who you want to produce and edit the documentation,
  • what tools you will use to create and maintain it,
  • what information you need to present, and how you want it presented.

Building a team

These decisions are relatively easy, but still require discussion and concurrence from the people involved. Practically speaking, seeking concurrence means agreeing to try something (an outline for the site, for example) with the understanding that things can be modified as the documentation evolves. The point is that the documentation does not have to be perfectly planned before you can start working.

Try to have a cross-section of your community -- both developers and end users -- working on your documentation to ensure that it is relevant to all users. Seek out, and specifically invite, non-developers to help. Determining who would produce documentation for src2pkg was relatively easy. Gilbert Ashley, src2pkg's author, is a regular contributor at LinuxQuestions.org, where he answers questions from users of his program. He invited three of us who regularly interacted with him in the Slackware forum to help him.

By design or chance, the three of us represented different types of users. I am firmly at the end-user end of the spectrum, while the other two are far more advanced users who have commented on development issues with src2pkg. Our respective skills led to a natural division of labor. My previous experience organizing and editing technical documentation naturally put me in the same role for this project. Another contributor with Web hosting experience, Piete Sartain, offered to host wiki software on a Web server and configure it. Agreeing on a division of labor, or at least volunteering for certain focus areas, breaks the overall project into smaller, more manageable tasks.

We had to decide whether to allow open contributions or restrict contributions to a known list of contributors. We decided to initially limit the number of contributors while we worked to set up the site, but may open up contributions in the future. Another option would be for the site administrator to create accounts for those who express an interest in contributing. That way the site is less likely to suffer from wiki spam, and monitoring the quality of contributions is easier. This solution works for our project because src2pkg is a relatively small application with a discrete set of uses. Setting up a wiki for an entire Linux distribution would require a different approach because of the much larger set of topics.

Choosing the tool

Using a wiki to create and maintain the documentation was pretty much a foregone conclusion; the question was which wiki package we should use. Wiki software allows people to directly edit Web pages and keeps track of the changes people make. Over the past several years, wikis have emerged as the preferred way for people spread all over the world to collaborate on a single document or Web site.

The decision we had to make was whether to use MediaWiki, the software used for Wikipedia (among others), or DokuWiki. We tried both. Initially, MediaWiki had a more familiar feel and looked more professional. The markup it uses is pretty intuitive -- inserting and formatting text went quickly. After getting most of the text into the MediaWiki version of the site, I moved it to the DokuWiki version and reformatted it. The editing toolbar in DokuWiki is slightly more comprehensive and easier to use than MediaWiki's, and editing text was marginally easier.

However, our reasons for choosing DokuWiki went beyond its editing interface. We found DokuWiki is more readily customized and, at the same time, easier to administer. DokuWiki, through a plugin called "nstoc," generates tables of contents based on subdirectories, which was just what we needed to have our master table of contents update each time we made a change. MediaWiki seemed to lack that feature, or it was not easily implemented. Furthermore, unlike with MediaWiki, features intended for more open collaboration, such as discussion pages, are not implemented as core features in DokuWiki. This seeming disadvantage was actually an advantage for our project because we had a small group of authors with password-protected access.

Creating and organizing the content

Our challenge with src2pkg was consolidating and organizing existing documentation and then adding to it where needed. Regardless of whether you are starting from scratch or looking to improve existing documentation, it is worthwhile to create an outline for the site. Outlines are not just the roadmap for your wiki, they are also the most essential tool for collaboration. To get started, I created an initial outline just two levels deep and emailed it to the other collaborators. After a few cycles of email comments we had a working outline that was three levels deep and ready to be filled out. The initial outline work was done without much reference to the existing documentation. We users and developers were hashing out the concepts that we wanted to present, the important details supporting those concepts, and the order to present them in. We were able to concur on the working outline quickly, which facilitated the remaining work on the src2pkg wiki.

The next task was to comb through the existing documentation and fit its text into the working outline. It was during this process that we did most of our work comparing MediaWiki and DokuWiki, learning about formatting and other features as we went. The working outline proved remarkably robust, needing no changes at the first two levels, and only the addition of a few headers at the third level. The actual work often involved taking two adjacent paragraphs and moving them to different major sections of the wiki. The result so far is a more organized presentation of the information one needs to run src2pkg and take advantage of all of its features.

Some work still needs to be done. The text needs further editing for consistency in style, grammar, spelling, and formatting. More importantly, some subsections still need to be written. Another advantage of having an outline is that headings with no text below them are easy to find. Follow-up email to fellow contributors can help coordinate who will write which missing section.

A final challenge is staying up-to-date. It is important for the developer to provide a changelog and even a "changes and hints" text file with each update so that the people working on the documentation can update it accordingly.

Conclusion

A documentation project, even one with a small scope, takes a lot of work. Wiki software makes collaborating on a project over the Internet more efficient, but there is no substitute for time spent at a keyboard actually working with text.

Projects like this tend to be most successful when everyone involved feels like they are doing 80% of the work. The best way to stimulate collaboration and involve other people is to do a lot of work yourself and then ask people to improve it. Beyond hard work, though, ensure the success of your software documentation by selecting a good team of people who represent a cross-section of your users, choosing a wiki package that meets your needs, and developing a good outline to organize your content.

Drew Ames is a transportation planner in Harrisburg, Penn.

Share    Print    Comments   

Comments

on Using a wiki for FOSS application documentation

Note: Comments are owned by the poster. We are not responsible for their content.

Using a wiki for FOSS application documentation

Posted by: Anonymous [ip: 143.166.255.41] on May 09, 2008 04:28 PM
When I started putting together the documentation for <a href="http://appsnap.gentrance.com">AppSnap</a>, I came up with a similar idea. I used <a href="http://www.tiddlywiki.com">TiddlyWiki</a>, which is a single file Javascript based Wiki engine. The result is a single HTML file that is bundled along with the app as the documentation as well as the official website for AppSnap easily maintained in source control.

There are some disadvantages to this approach such as having one perspective (official website in AppSnap's case) dominate over the other. The advantage is that the time spent in expansion and maintenance is much much lower, allowing for more time to be spent on development.

This approach is especially helpful for projects just starting out and can be enhanced once the project is established and more resources are available.

#

wiki makes sense

Posted by: Anonymous [ip: 66.114.78.90] on May 10, 2008 05:40 PM
For an open source project run by volunteers, using a wiki for documentation just makes sense. It doesn't even have to look like a wiki, and it doesn't have to be editable by the general public. We did the web site for <a href="http://www.citadel.org">Citadel</a> using DokuWiki, after finding Joomla a bit too cumbersome for the task. DokuWiki was very easy to customize -- we were even able to convert our Joomla theme with about an hour of template editing.

Wiki editing controls do not appear unless you're logged in, and only the developers and site maintainers are allowed to log in. But we're very, very diligent about one thing: whenever someone asks a good question in the support forum, we add another wiki page documenting the answer. By doing this, we've ended up with a Knowledge Base for the program. And if you ask me, that's more comprehensive than a "FAQ" -- let's face it, the FAQ's for most open source projects aren't made up of actual questions that were asked -- they're more like a README written in question-and-answer format.

#

Using a wiki for FOSS application documentation

Posted by: Anonymous [ip: 70.91.34.61] on May 12, 2008 06:56 PM
I'm glad to see that so many options exist for people wanting to use wikis for user documentation, although that last post _does_ seem more like an advertisement than a comment.

#

Using a wiki for FOSS application documentation

Posted by: Anonymous [ip: 62.49.242.3] on May 14, 2008 01:47 PM
Searching for a Wiki at the moment for my office - MoinMoin is coming out on top because of good attachment support - about out of the box and with add-ons( associated attachments listed at the footer of a page). Only personal 'drawback' is it is python based and I was trying to standardise on php.

Many major projects use MoinMoin including fedora and ubuntu.

#

This story has been archived. Comments can no longer be posted.



 
Tableless layout Validate XHTML 1.0 Strict Validate CSS Powered by Xaraya