Author: Drew Ames
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.
Category:
- Collaboration
