At the OSGi Community Event in London recently, a complaint about the available documentation was raised. The problem is that whilst the RFCs are very well written, they really describe the contract of the service provider, rather than an end-user. As a result, you have specifications that (like JSRs) dive deep into nuances of behaviour, but either gloss over or completely ignore how end users might adopt it.
This causes problems in two places. Firstly, the requirements of “How can I use...” aren't answered, and secondly (probably more importantly) “Why should I use...” are never answered. It's implicit in the formation of the RFC that the Why question is already known and accepted – otherwise there wouldn't be an RFC in the first place. Sun achieved this with the Java Language Tutorial book, a much better learning point than (say) the Java Language Specification. Yet all we have are the OSGi specifications from the official osgi.org website.
The reason we don't have such resources, of course, is that the OSGi Alliance doesn't have the funds to do this. There's plenty of information on the web, but almost all of it falls into either runtime-specific examples (Equinox, Felix, Knopflerfish etc.) or simplistic “An OSGi bundle is really just a JAR with extra Manifest entries ...”. And there's not really a single place to go to.
Community-sourced information is fairly easy to come by, given a community with enough interest. There seems to be the interest for the Eclipse community; after all, wiki.eclipse.org has an ever greater number of contributions, and there are a number of Eclipse help documents which are sourced from the wiki.
The problem is that all the existing wikis are (necessarily) vendor-specific. The Eclipse wiki is a great place to go to find out about arcane configuration information for Equinox or ECF, but it's not likely to say how to configure Felix. Similarly, the Felix site has a number of useful tutorials on how to use standard OSGi services, but not much on Remote Services Admin – largely because Felix doesn't have an implementation yet. By putting it all in one, well-known place, we could overlay information that crossed boundaries and made them available to all.
I therefore propose the creation of an OSGi.org hosted wiki that the community could participate in to fill the missing gaps in the user-end documentation. When you look at wikis generally, they're a great way of assimilating information; and one of the advantages is that ownership of the material doesn't preclude updates by new maintainers (or even drive-by typo fixing), as well as fleshing out information or adding extra gotchas.
For this to work, there needs to be a few things to make it happen:
- Copyright – does it follow a Wikipedia or Eclipse wiki model, where copyright retains with the authors that contributed it? Or does it require copyright contributions to be assigned to the OSGi Alliance? Requiring copyright assignment may well detract people from wishing to contribute.
- License – what license is the information to be used under? Wikipedia predominantly uses GNU Free Documentation License, but many companies shudder whenever GNU is mentioned. Alternatively, one of the Creative Commons licenses may be more applicable, like CC-BY-SA or CC-BY may be appropriate.
- Accounts – will it be possible to hook into an existing authentication provider using OpenID, like StackOverflow authenticates against Google accounts? If people already have an ID, then they may be much more likely to contribute towards it.
Actually creating a wiki, and getting the hosting, is the easy part. But the right decisions need to be made ahead of time in order to ensure maximum participation – and thus benefit – for the entire community. A license which doesn't permit commercial re-use, or requiring copyright to be transferred to the OSGi Alliance, are likely to cause problems for some angles. But those needs must be balanced against an alliance with legal duties to its members to ensure that it doesn't expose itself, either in terms of opinions expressed by others or by bad advice – a suitable distinction between “official information” and “community provided information – use at your own risk” needs to be present.
The balls are in motion, and discussions have been started on the subject. In the meantime, please feel free to comment on this article and suggest what contributions or licensing issues you feel are appropriate, such that there is a set of information available to those who need to make the decisions.
For the purposes of making it explicit, I have no formal connection with the OSGi Alliance and I am speaking out about my personal thoughts, not of my employer. I have a vested interest in making OSGi succeed, and to that extent, having a wiki and being a part of its construction makes sense to me.