What factors are most important to run a documentation project?

Asked by Roger Sperberg on 2009-04-15

I have a number of questions about creating a project for documentation of an open-source project.

Launchpad itself deals with its documentation by using a help wiki that links to the launchpad-documentation sections for Answers and Bug-tracking (and eventually translations, I guess). The actual documentation, however, appears to be created in the wiki and completely managed there (as opposed to treating it as code and managing it in Launchpad itself).

So my questions mostly deal with the best alternatives for creating documentation and what factors led Launchpad to its particular solution.

I want to begin creating documentation for FBReader (fbreader.org). There are two separate reasons I thought Launchpad would be the best place for this.

First, FBReader comes in more than a dozen different varieties, each tailored to a specific device and OS. So material documenting a particular feature might use the same text for all the distributions but different screen captures for each one. Using Launchpad to keep track of all the variants seemed like a good idea, especially as some features are not implemented in every version for every device.

Second, there are already ten translations of the mini-help file that comes with FBReader and of its interface strings (aka messages). Launchpad's translation sharing seems the best approach I've seen to facilitating localisation to new languages. And getting the new documentation translated would probably also be well-served by the same tools.

In a single language, with only the latest version to describe, I think a wiki may be the best solution, especially because people are familiar with how to contribute. But how is Launchpad planning to deal with translations of Help pages?

Wiki's are also very page-oriented. If the documentation runs only 20-50 pages (is Launchpad Help larger than 50 pages?), do you think it is worth breaking the documentation into smaller segments (sections or paragraphs) when managing it like software code?

Managing all the variants possible for FBReader inclines me toward a Launchpad-type solution. But are there any writing-collaboration or editing-collaboration tools? In that respect, I can see why you opted for a wiki approach for the explanatory pages.

What wiki software is used with Launchpad Help? What advantages does it have for a documentation project as compared to other wiki software?

I appreciate whatever responses you can provide to help us with our decision. Also I'd greatly appreciate it if you can point to any other sites that discuss managing an OSS documentation project.

Roger Sperberg

Question information

English Edit question
Launchpad itself Edit question
Matthew Revell Edit question
Last query:
Last reply:
Here's a guy who might know a thing or two about documentation. Assigned to Matt. — Danilo 20090501 flacoste Pinged Matt about it. 2009-06-03 gary pinging Matt :-)

Launchpad uses MoinMoin for its help wiki. The advantage of working with a wiki is that the barrier for entry is lower - when users want to help extend the documentation they can just jump in and do it.

Alternatively, some projects use source controlled text formats, like docbook or ReST. Those provide a slightly more structured solution.

Can you help with this problem?

Provide an answer of your own, or ask Roger Sperberg for more information if necessary.

To post a message you must log in.