I think it would be great if Atlassian were to provide a more full set of actual example uses of their APIs, versioned and released along with each Atlassian product, as reference implementations.
Atlassian uses CrowdService, UserAccessor, GroupManager, user and group paging classes, etc. within Confluence, but It is much easier to maintain a codebase with an implementation of the product than it is to maintain information about these APIs in a wiki, because the wiki documentation may look correct, but then oops- maybe it isn't complete or totally up-to-date. I'm not saying that it has to have anything more than a v2 plugin with a basic UI either, and it may not even be that practical. (I hope that no one's ever accused Spring of providing a PetClinic application that they couldn't use in a real veterinarian's office!) I was able to maintain v2 of the Confluence Space User Management plugin for Confluence fairly easily until Confluence v3.5, at which point I'm not sure where I needed to use UserAccessor and when to use CrowdService. Such a reference implementation would have helped in this case.
Atlassian has some wiki documentation about writing authentication classes. (They are kind of "plugins", but they aren't.) However, when Confluence was upgraded, the wiki documentation stayed mostly the same and I wondered whether it just wasn't maintained, so I attempted to upgrade the Confluence Shibboleth Authenticator to an Atlassian v2 plugin. This didn't work. In a ticket, Matt told me that it can't be a v2 plugin, so I tried a v1 plugin. That didn't work either, and I thought I understood that it could use Spring to get access to the beans. That didn't work either, then I was told it had to be loaded via classloader and to use ContainerManager and that ContainerManager had to be called after the beans were instantiated, so it couldn't be called in the contructor of the authenticator. The sad part was that this was the way the plugin was written in the beginning. I had assumed that when I was adding usage of CrowdService that getting bean instances when required was wrong and that I should make it an Atlassian v2 plugin and use constructor injection, but that had been incorrect. It is fine to have those sort of learning experiences, and by a short paragraph or two in the wiki, maybe this would have been avoided. But, having a reference authenticator versioned and released with Confluence 3.5 that uses Atlassian beans such as CrowdService and perhaps had a few choice comments as to why ContainerManager was having to be called at time of need vs. contructor injection as a v2 plugin would have been extremely helpful and would have saved a lot of time.
Another example is that one change in Confluence 2.6 included a breaking API change that required reflection to be used to call the appropriate method. This was fixed in a later version of 2.6, but I had to add the reflection hack that David Peterson came up with to the Confluence Space User Management plugin and it was part of CSUM's codebase until recently.
If you are looking for another major player in the Java development world that provides similar examples, look no further than SpringSource. They've provided the PetClinic application longer than I can remember, and provide additional examples as well for Spring and other frameworks. (Even Spring Roo provides a clinic application.) Another project I've recently worked with that provides examples as part of their codebase is Liferay. They provide a set of examples that they version along with the product that provide sample portlets using various frameworks.
By keeping the examples and documentation in the code, and releasing them with the product, Atlassian could also potentially significantly decrease the amount of work maintaining the wiki documentation, at least over the long-term. (There would need to be a short term project to cleanup and remove examples from the wiki.)
You could argue that instead of writing example code that compiled with the version of the product, why not just add more examples of API usage to the Javadocs. Java developers like to sometimes have examples provided in the Javadoc header for each class, and in some cases this might be helpful to add. However, you can relay concepts more easily about how beans should be wired and best practices in plugin development by providing example code that compiles against the version of the product and its included libraries. I think both options have their place.
I know that there are already some plugins provided and maintained by Atlassian that are open source. However, I think that it would help "eating your own dog food" even more by providing a more full set of examples/samples that are built, tested, and released with the corresponding Atlassian products.
This wouldn't make Atlassian less agile, because they'd be spending less time working on bug fixes after a release. This new documentation (the code being the how-to documentation) would be checked at compile time on every integration build, and the wiki documentation can't even do that. It would also reduce the number of support tickets and increase the number of customers that would rave about Atlassian products' ease of extensibility.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.