Pat’s Point of View

15 Responses to “Confluence, thy enemy’s name is Pat”  

1. 1 Jonathan Nolen Dec 2nd, 2006 at 9:56 am

   Hi Pat,

   I’m truly sorry that customizing Confluence themes is such a pain. We agree, it’s definitely more complicated than it should be.

   As far as the UI goes, that an area that we plan to focus on again soon, in the not-too-far-distant Confluence 3.0.

   I would love to see what you come up with, even through all the headaches. We’re always looking for more themes, particularly those that are simpler and easier to get started with. If your interested in sharing, please drop me a line.

   Cheers,
   Jonathan

   P.S. in a possibly related note, we’re looking for a UI developer/designer to join the Sydney team, so if you (or anyone you know) is interested, give me a shout. Job description here: http://www.atlassian.com/about/jobs/ui-designer.jsp.

2. 2 Pat Dec 2nd, 2006 at 11:00 am

   Jonathan, that’s the best response I’ve received with regard to Confluence. The support and developer documentation is definitely not as friendly. I’m not sure if I’ll be able to share the theme I’m working on…I’ll discuss it with my client.

   FYI they’re using it as a call center Knowledge Base (part of their intranet), so the main priority is to simplify the interface and make it easy for staff to get the information they need. I just wish I didn’t have to jump through hoops to achieve this, like creating a JAR file for the theme, uploading it and then testing the results! I find that, most of the time, doing this causes the server to stop responding.

   It’s interesting you mention that job vacancy, will the job include building some abstraction between structure and presentation? That would make things a lot easier as I wouldn’t need to override (indeed re-write) macros and includes just so I can have some clean, semantic XHTML that I can style properly? If I didn’t have to undo some much of what strings together the site, I would be finished by now.

   Reading over my post, and this comment, I sound very much like a designer! Maybe I am now? I want to simply change the layout and appearance of features, and doing this should not have to involve cracking open code, restarting servers or working around obscure issues with how (perfectly valid) CSS code is parsed when within a Velocity decorator.

   Sorry, I’m ranting again. Thanks for your comment, I know you guys are probably trying to rectify these issues, and I do look forward to seeing 3.0, cheers.

3. 3 Tony Truong Dec 4th, 2006 at 9:36 am

   “I just wish I didn’t have to jump through hoops to achieve this, like creating a JAR file for the theme, uploading it and then testing the results! I find that, most of the time, doing this causes the server to stop responding.”

   In version 2.3 of Confluence, you will be able to run unit and functional tests for your plugins against a Confluence WAR by using Maven 2. Some of the benefits of doing so are:

   * You can test against the latest code changes in Confluence
   * All tests are automated
   * Combined with Atlassian Bamboo or other Continuous Integration packages, you can be notified
   * Combined with JIRA or other Issue Tracking system, you can keep up to date to the latest bugs and feature request for your plugin
   * You will be testing against a fresh Confluence Instance - you will not need to test against your server

   You will also pick up other benefits that are Maven 2 specific - like Dependency Management.

   Does this interest you?

4. 4 Pat Dec 6th, 2006 at 7:49 pm

   I look forward to it, Tony.

5. 5 Phil Wilson Dec 8th, 2006 at 8:10 am

   Tony, unit testing doesn’t help you work out if you’ve put the macros in the right place or not. Unless I’m fundamentally misunderstanding what you mean by running functional tests of course :)

   Pat is right, and developing new UI layout is really, really hard to do. I say this as a Java developer. You should try talking to our web designer :)

6. 6 Pat Dec 8th, 2006 at 9:18 am

   Phil, I’m curious to know what you mean by putting them in the wrong spot. I’ve been looking for a way of overriding macros.vm (so I can clean up the markup) but I’ve had no luck in doing that using a theme. Have you come across a way of doing this?

   Are there any other specific issues you’ve had?

7. 7 Phil Wilson Dec 11th, 2006 at 9:23 pm

   Well, I mean you can insert content in themes using macros, but until you’ve installed it, you don’t know if you’ve put the content in the right place, especially if you’re including a velocity template which calls other macros.

8. 8 Alex Dec 13th, 2006 at 12:59 pm

   Just a note to say that I avoided a lot of demons by not creating a theme plugin in Java at all, but just circumvent the problem and create my own directory space for Velocity templates which I point the Wiki layout to. this of course has its own set of demons, but alas different to yours. Sorry I can’t help you out much there.

9. 9 The EGA Jan 7th, 2007 at 2:50 am

   Confluence is an abomination from the Sysadmin point of view, mostly because the documentation is gappy, sloppy, or just plain wrong, but having used Atlassians ’support’ (ho ho ho) I can tell you I would never use Confluence in a production environment. Never.

   Confluence support groups are popping up around the place…which indicates a failure rather than a success for Atlassian.

10. 10 Pat Jan 8th, 2007 at 9:43 am

    Can’t aqree with you more about the documentation. I couldn’t work out how to shutdown and restart the server on unix, because A) I can’t remember anything I ever knew about unix sys admin and B) all the documentation assumes Windows.

    I asked why this was the case and was told that most people run Confluence on Windows and that it would be too expensive to write doco for all platforms. Hmmm

11. 11 Eric Aug 2nd, 2007 at 9:48 am

    Hi Pat,

    I’ve been “volunteered” to help out with our Confluence / Jira implementation. Can you point me to some good resources or books that could help in the maintenance and upgrading, etc.? Any help would be appreciated. How have you managed so far? Are you happier now?

    Thanks for the help!

    Eric

12. 12 Pat Aug 2nd, 2007 at 11:16 am

    Eric, to be honest, no I can’t point you to anything that might help. Some of the other people who have commented might be able to though. Confluence is very popular, so there a lot of people out there who have gone through (or are going through) what you are, so they should be able to help you.

    With regard to whether I’m happier now, well yes :) I haven’t had to do anything more with Confluence for some time. And my situation was not typical, I was trying to customise the look and feel of Confluence for a client who was using it for a purpose other than what it’s usually used. Sounds like you’re going to be approaching it from the systems admin point of view. So my troubles were atypical, I think. That said, I still think it would be good if Atlassian made the presentation engine easier to customise.

13. 13 jd lima Aug 3rd, 2007 at 11:44 am

    Pat,
    Just wanted to sympathize! We’re staggered at how complicated and confusing is the seedy underbelly of Confluence, just trying to implement a plugin and alter the UI a little! *sigh*

    Best luck (to us all!),
    -jd.

14. 14 Jonathan Sep 27th, 2007 at 4:51 am

    Pat,

    You are spot on with your description. Confluence is a nightmare to extend. The documentation is deplorable, even embarassing for a product that costs more than a few dollars, or even one that doesn’t. (Witness the usually effective docs at the jakarta commons.) In addition to this it is monstrously slow, as compared with other wikis. I have wandered through the source (in an effort to understand why the product does not function as advertised,) and indeed it is quite complex. In fact, I would say they bit off far more than they could chew.

    However, my biggest beef with this “customizable” app is that is seems to be written for designers, not programmers; not at all. Performing even the simplest of things in a user macro is arduous. (Try manipulating the DOM; it is either impossible or so deeply hidden as to be unavailable.) One of my first goals was to write a reasonable editor for the macros since the provided text box is pre-alpha work. But without any docs this became impossible to do in any reasonable time. All but the most trivial of macros are simply too expensive to undertake. We have been able to build plug-ins to perform things like adding email notifications when documents change, adding interfaces to other databases and performing actions exposed by other apps (through the DB and http requests,) but like macros they are poorly documented with no real way to test them, and with error messages that are essentially meaningless. Of course our first deployed plug-in was to add a library to extend the paltry number of objects found in the velocity context, some of which simply do not exist as documented! (What ever possessed them to use velocity?)

    To be sure, for writing and sharing pages it is very effective, and my organization has definitely benefited from that. But that would have been possible without a purchase. Of course, it has definite holes like editing a page whose macros cause exceptions, returning to the previous page after removing a parent or deleting a page and a treeview that remembers its state. (I built something like that 3 years ago with simple javascript!) The ironic bit is that we bought it because it seemed to offer the best customizability; I rue that day. Thankfully the original projects we had in mind, which seemed very cool at the time, have been abandoned in favor of easier things like integrating our webapp with remote manufacturing software. Well, that’s not really fair as we know our stuff pretty well. Ok, scratch that last point.

    Sorry for the rant. The upshot is that this is pretty good as a wiki but it is not customizable any more than myspace.

    Best of luck
    -J

15. 15 Pat Sep 27th, 2007 at 4:21 pm

    Thanks for your comments Jonathan. Seems like I only experienced the tip of the iceberg.

    On a more positive note, at the recent OZ-IA conference I learned that Atlassian have hired an experienced User Experience designer to tackle the customisation and extensibility issues.

Leave a Reply