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.
A colophon historically was a page in a book that gave information about how the book was published. It usually listed the fonts used, where it was printed, who printed it, what kind of paper was used, and eventually what technology was used to produce the book.
Colophons are throwbacks now. Most publishers don't bother any longer, which I think is a shame. I'm on a minor quixotic mission to resurrect the practice.
Typography
The title and side headings use the Skia font, Matthew Carter's update of ancient Greek lettering. The monospaced font in the title is Consolas. The rest of the text is determined by the fonts available on the client using CSS. I've specified the following order: Lucida Grand, Lucida Sans, Verdana, Sans-serif (generic).
Design
The photos are of a pair of bizarre boxing frog pens that were given to me as a gift. Their arms are extremely muscular, and you cause them to jab with small levers on their backs. The heads swivel to the sides, and when you press down the nub of the pen, a cheap red LED lights up their torso. Their faces have the maniacal grin of the truly unsettled. I took the photos with a Canon digital camera, and touched them up using Apple's iPhoto and the GIMP. I used the GIMP to create the header, and the side heading graphics.
The color scheme was determined after manipulating the colors of the photos, and was in some small part influenced by a Paul Frank t-shirt.
I coded the HTML and CSS using Apple's Xcode and TextPad.
The name
The term verso means the left page of a book, as opposed to the recto, or right, page. The first page of a book, and therefore all odd numbered pages, are recto pages, while all even pages are verso pages.
This release of the J2EE Tutorial is for Sun Java System Application Server 8.1 PE 2005Q1. The primary update was a rewrite of the Duke's Bank case study to use container-managed persistence for the entity beans. The previous version used bean-managed persistence.
For those who have wondered about how to use sequential primary keys in CMP beans without breaking CMP's database independence, Duke's Bank now uses a separate CMP bean/db table that retrieves and increments ids when creating other CMP beans. It's still not quite as easy as using sequences in the database itself, but it does the job, and it's fairly simple.
Look for some new advanced JAX-RPC examples in the next Tutorial release.
