Verso

For J2EE 5, Sun is putting a lot of effort into making enterprise applications easier to create, deploy, and use. Deployment descriptors consistently come up as a source of discontent with the J2EE development process. Right now we're scoping the J2EE 5 Tutorial, and would like your feedback on how the Tutorial should deal with deployment descriptors.

Of these three options, which do you prefer?

1. No discussion of deployment descriptors, provide pre-assembled JARs/WARs/EARs
2. Provide detailed instructions on assembling the JARs/WARs/EARs with a graphical tool like deploytool
3. Provide both "fast track" instructions (option 1) and "slow track" instructions (option 2)

Related to this, what is your preferred development environment?

1. IDE (like NetBeans, Java Studio Creator, Eclipse, JBuilder)
2. command-line tools & text editor (vi, Emacs, TextEdit, etc.)

Tim Bray's remarks on the death of documentation are typical of many engineers I've encountered over the years. For example, the chief architect at an application server company I used to work for thought that documentation was a symptom of incomplete or unintuitive tools. That is, the existence of documentation was an engineering flaw, and that a sufficiently well designed piece of software would not require any explanation.

Tim Bray's thinking is not quite so extreme, but the assumption is similar: coordinated documentation efforts are hopelessly flawed endeavors. Why not cut out the middleman and just have the users and engineers write the documentation, in the form of a Wiki where problems could be posted and solutions contributed for all to see?

I should point out that Udell's article was about solving the problem of technical support docs, but Bray picked up a few overtones in the article about documentation in general being crappy and sort of ran with it.

Personally, I fail to see the necessity of an excluded middle here.

First of all, the set of products or pieces of software that could be documented completely through a user-written Wiki isn't very large, because the product/tool needs to be fairly simple for a tabula rasa user to even know where to start with it.

Secondly, although I find Google and mailing list questions and forum postings quite useful for solving specific problems, these little snippets of information do not make a coherent whole. A related point is that the people posting the questions are often familiar with the system generally, in fact are expected to be familiar with the system, and are having problems with a particular area. What is the standard response to newbies who post general questions like: How does $PRODUCT work? RTFM.

Thirdly, the probable success of shunting the responsibility of writing doc onto the users, with contributions from engineers, is highly unlikely, to put it mildly. Somebody has to do the thankless job of writing this crap, engineers rarely have time to even review the material produced by doc teams (to say nothing of actually doing it themselves), and there is something to be said for coherent, grammatical, and style-checked prose when using ever-more-complex technology.

So, I'll conclude with a proposal that is hopefully obvious when you think about it: Wouldn't it make more sense to deliver the documentation in a format that could accomodate general discussion of the system as well as user supplied questions and answers? Merge the manual with the Wiki, yo? Some projects do this, like the PHP docs online and the PostgreSQL docs.

For the three people left in the world who still care about hockey (including myself, and I suppose our fearless leader, so that leaves one--any takers? anyone?) Salon.com sports columnist King Kaufman's take on the NHL lockout is a good read, and explains the utter incompetence of the monkeys that run the NHL.

Basically, the owners backed themselves into a fiscal corner due to optimistic, if not outright delusional, revenue projections and the false economy of expansion fees. The house of cards began to collapse because a) better coaching, conditioning, and materials science (think about Patrick Roy's mammoth foam legs pads, compared to the leather-covered burlap sacks used in previous eras) decreased scoring significantly, and 1-1, 26-total-shots snoozefests in mid-February for some reason didn't increase the interest of the casual sports fan; b) despite that kind of on-ice excitement, the explosion of cable and satellite didn't bring a significant increase in television viewership, but did result in NASCAR races ("He's making a left turn, Jim.") and competitions of large northern European men carrying boulders outdrawing NHL games; c) with the exception of Denver and Dallas (i.e. two of the league's best teams) and to a lesser extent San Jose, the western/southern expansion teams have neither expanded the hockey fanbase nor captured the local sports fan's imagination.

So now the owners want a hard salary cap, because they've demonstrated they cannot understand basic economics, resulting in financially unhealthy franchises, and the league led them along the primrose path to Abaddon by failing to understand the hockey market, the sports market in general, the entertainment market in general, their fans, societal trends, or anything that was happening at any point between 1991 and 2004.

Unlike the last baseball strike, there has been no real fan backlash against the players that can be exploited by the owners and league, probably because the only people who miss hockey at all at this point are the most ardent fans, and Canadians, who the league doesn't really care about much anyway. Nonetheless, the league has been trying to foment fan revolt in the media by accusing the players union of being greedy, a tactic which would work better if the union hadn't just proposed a 24% across the board salary cut. Meanwhile, the NBA is looking a lot more interesting to the casual sports fan (player/fan stand fights notwithstanding), and SportsCenter is making jokes about a forgotten sport called hockey.

If the league ever decides to look up the meaning of the phrase "negtiating in good faith," maybe in time for the start of the 2006-2007 season, they'll probably notice that a third of the players are happy playing in Europe (where they don't have to deal with the Tie Domis and Derian Hatchers of the world), and the fans are spending their season ticket money at the multiplex, watching cheeseball elimination ceremonies and CSI reruns on their TiVo, and getting excited about the Miami Heat/Dallas Mavericks game on ESPN. Meanwhile their Steve Yzerman jerseys are getting stale and dusty in the closet, and they can't remember which team last won the Stanley Cup.