Introduce yourself at FOSS4G (was Doc Experiments and Alternatives)

Here is another draft blog post turned up in my recent hunt through the revised blogger ... this is mostly text / rant that I removed from my review of the excellent Open Layers book published a few months ago.

I will be attending FOSS4G in a couple of weeks - and in a fit of planning I am not putting on a workshop this year - leaving me with a couple of days to hang around the OSGeo booth. Drop by and introduce yourself :-)

I would love to hear your thoughts on this topic topic of documentation / communication as it is a key factor in succeeding with open source (for both prospective users and also for projects themselves).

There is a spectrum here between the ideal balance of a wiki (where users can contribute to a project documentation while developers work on fixing issues) through to the documentation being held in reserve "for pay" as a way to fund development.

• While I am interested in seeing projects set up to succeed I do not like seeing documentation as a bargaining chip; simply as it is too important to initial success and adoption.
• Another popular alternative is to withhold updates as that only effects existing users while allowing developers to focus on their paying customers. It does arrange a tricky situtation with resellers - my recent Seagate NAS 110 vs Lion has left me placing that product in a closet and buying a time capsule while open source developers waited to get paid.

In any-case here is the original rant... and yes the ideas have been duplicated on other blog posts of mine.

---

As a follow up to my opening/rant for the Open Layers 2.10 Beginners Guide here are a couple of experiments in documentation that I am aware of:

Book Required

One extreme is projects where you need a book in order to be successful. I work with a number of software packages that fall into this category such as the Eclipse Modelling Framework and BIRT. This can be offset by a good 5 minuet Quickstart, but you need to keep the target audience for the project in mind.

Documentation For Pay

One experiment I am not found of is keeping the documentation "for pay" while making the project itself open source.

The User-friendly Desktop Internet GIS project works in this manner, resulting in a heavy amount of work to keep documentation up to date (with no possibility of sharing the work). While this is a good way to have a project earn its keep, it does have a serious impact on adoption, and can only be successful with regular training courses.

To offset the above disadvantages we have a the introduction material online for free as a sample; and make all the materials available to academics (under the condition that their professor sends us an email request, and that any corrections are sent back).

Wiki

This should really be the best solution, it is one we tried for GeoTools that ended up in abject failure. Here is what abject failure looks like:

• I ended up writing 80% of the docs anyway
• Vandalism

Still the business process behind this one is sound; rather than trying to turn users into customers; try and turn them into contributors to the project. Better yet by asking for contribution to the documentation you can leverage their unique expertise - and endless supply of questions and a fresh set of eyes.

User List

A user list is a staple of open source projects, the general value being:

• Remove day to day questions from the development list; allowing developers to focus
• Allow users to help themselves

User lists have a really mixed track record in this respect, the GeoTools user list is mostly successful due to a few dedicated volunteers such as Micheal Bedward who answer most question, and take the harder questions over to the developer list for discussion.

Personally I am not sure if it is worth it, as exposing the developers to day to day questions would be a great motivation for improving documentation.

There are also many examples of user lists falling into madness and requiring moderation making a user list a pretty risky proposition.

Question and Answer Sites

We have started listing Q&A sites in the GeoTools support documentation. This is both to take the place if the wiki, and to threaten the value of the user list.

The really nice part of the Q&A sites is the way answers that are valued bubble up to the top (and if the answer that bubbles up is a workaround it is a great excuse for me to address that problem that makes the workaround required).

Discussions / Answers tend not to "expire" the same way email threads on the user list do.

The downside is that GeoTools is externalising our documentation and relying on another organisation (in this case a commercial one) to both handle the issue; and monetize the result.

It would be good if some revenue from these sites flowed back into the open source projects producing the questions.

These sites also have a chance of offering excellent "customer service" with relatively little duplication of effort. As such this approach is used by OpenGeo for their OpenGeo Suite. I really feel it is nice low effort alternative to running a user list.

Direct Collaboration

I have had a standing offer on the GeoTools user list for collaboration on documentation topics; this is the best of both worlds with a user supplying questions, editing and review and a developer trying to remember how things work.

While this is an ideal balance in terms of producing quality documentation; I have yet to see a way to make it commercially viable. My best though to motivate this style of documentation is partnerships with OSGeo committees such as the education committee. There does seem to be a lack of understanding with respect to value of documentation (ie how to pay for developers time) that I have been unable to address.