The JBoss Spring integration project (Snowdrop) seemed a bit too simple to me. After all I have used JBoss with Spring and to be honest it didn’t seem so complex to me as to deserve a whole session. Maybe it was useful for other people. For me it felt a bit like a marketing session (“look we support Spring too”). But I’m a cynic so maybe I’m just perceiving it wrong.

I liked the presentation on the new JSR-299 which is called Contexts and Dependency Injection (CDI). I my opinion the talk was a bit too focused on the DI part. I’m really into the topic of context and state management lately which is a topic which is still feels like an unsolved problem around web frameworks (Of course: full-stack-frameworks like Tapestry, JSR-299 or  Wicket offer proprietary solutions but then you have to buy into the whole framework which might be good but might also be a showstopper). It also seems we have just replaced XML with annotations. All the new frameworks are very annotation-heavy. It will be interesting to see how this plays out when you combine all the solutions together. I doubt the code will be very readable. But Pete Muir did an excellent job with presenting it.

The migration from WebLogic to Tomcat by Joel Tosi spoke to my heart. Joel explained how the usage of the application server WebLogic at the CME lead to a huge complexity problem and how they solved it by basically stripping their platform down to the bare minimum (from a full blown JEE-stack down to Servlets and Persistence). It think complexity is a major problem with today’s solution. Often simplistic examples are used to sell new technology but if the application grows bigger it’s not clear how frameworks or programming models will scale up.

To sum it up: I enjoyed the conference a lot. It learned a whole lot of stuff and sometimes felt like the dumbest person in the room (I still don’t know how ESBs or BPM works exactly – it remains a mystery to me). The new technologies look good but I think a more humble approach would suit them better. After all EJB2 was praised as a great solution so we should be a bit more careful. Maybe we’re always falling for the same pattern. Simplistic examples are good to explain a new technology but sometimes it would be interesting to present the big picture and show how it plays out in real applications.

I must admit that I always had some kind of a love-hate relationship with Tomcat. The classloader had some bad issues when reloading a webapplication too often and often killed the complete server. Taking down all of the other webapplications too. Although this has gotten a lot better recently it’s still bothering me a bit.

Since I had some time after my last project I started investigating other open source alternatives. I often heard of Jetty, praised for it’s speed and simplicity, it seemed like a great alternative and I played around with it a bit. I really liked it since it was simple to use and easy to deploy but as I started to google for things like performance measurements or how to use it with a security manager I didn’t really found a lot of documentation (compared to Tomcat) and the performance doesn’t really doesn’t seem to differ from Tomcats.

So I’m once again going the Tomcat route. It has a big community and is even used in military and government organizations. It’s really not a technology decision (although I think Tomcat is solid) but more political thinking.

It will also save me some time which I can invest in trying out other technologies. Meow…

Andreas Rüping suggests in his book Agile documentation to create small and highly focused documents, targeted at:

• An explicit target audience (This dictates for example the kind of information and the tongue the document is written in)
• Readers interested in a special part of the project/information (This dictates the contents and structure of the document)

These documents are laid out in a document landscape. The landscape is formed by different types of documents (for example: Requirements specification, conceptual description, business goals, architecture overview, API description, etc.). The landscape is developed over time by creating template and example documents. If you start a specific project you simply pick the matching documents and fill them with contents. The maintenance of the landscape can be a project in itself or you can just develop it while you are working. The result is a (more or less) coherent set of documents across multiple projects which are short (easily digestible), focused and easy to navigate. You will become more and more familiar with the types of document over time and find the relevant information more quickly.

The Antagonist of this type of documentation is the almighty project document. It is a chimera born out of all different kinds of project documents and information. Most of the time it’s this kind of document which is shown to clients who really care about documentation. Often supported with sentences like “Look, we produced over 200 pages of documentation”. If you take a closer look at the document you will most often notice that the contents consists of:

• A (too) general introduction to the topic of the project
• A definition of goals
• Copy and pasted examples from the manuals of the libraries used in the project
• Duplicated reference manual sections of the libraries used in the project
• The complete source code/config files (of course not in sync with the VCS any more)
• No really clear statements of what should be done/has been done
• Information from different time frames (planning/implementation/review)
• …

This information is often not structured in a very good way and delivered in a PDF without a navigateable table of contents (so that page numbers in the ToC differ from the real page numbers) or hyperlinks. The fellow developers or administrators who have to work with the documentation will only get half of the needed information out of the it and will waste time checking back with the management folks. The resulting product will most certainly miss some important aspects and if you have to look back at the project you will surely be confused.

Additionally this document violates an important principle of concurrent access to a resource (speaking: teamwork): Keep the chunks which need to be accessed by multiple persons at the same time (programs) as small as possible. In a web project you often separate the program into a set of files defining the output (templates, view files, you name it) and a set of libraries/scripts/whatever. This is not only to keep the webdesigners from having to read the program code but also to allow the presentation and the program to be edited at the same time. Do yourself a favour and not only spend time designing your software, also design your project documentation.

One last word: Of course I consider myself guilty of having produced some kind of an almighty project document (although maybe not as evil as described above) from time to time. You simply can’t do  everything right in a constrained environment like the real world. But the more often we stress the importance of good documentation and information design we will maybe come to a point where good documentation is considered really valuable and therefore honoured and budgeted with time,dedication and respect.

Do you have your own thoughts documentation? Ever or never produced a real beast? Please comment.

Dilbert on documented processes