So you’ve released a new application or library? Congratulations, and thanks for supporting the software community in some way. GenericoApi 1.0 sounds great and I’d like to use it for this great idea I have, so where is the documentation? Yeah, I can see the Javadoc methods on your site but… oh, that’s it? Right…

I’ve been in that situation far too many times. So let’s clarify something: if you create a library that is to be worth something you’re going to need the following.

• A high level overview. Far too many projects (SourceForge sites, I’m looking at you) think that just because a visitor ended up on their page that said visitor knows exactly what the project is about. This is rarely the case. I’ve said this before: a clear description of what you do at the top of your front page, always.
• A technical overview. A very detailed overview of everything your API/app can do, catering for the most knowledgable, hardcore contingent of your userbase. This is important for both early adoption and to show you actually know what you are doing; impress the cult leaders and the rest will follow.
• The API documentation. If you’re writing in Java, then I want to see a detailed and descriptive set of Javadoc documentation. This should make very few assumptions about knowledge of the system you use, and any assumptions should be clearly linked. It should be clear how to construct and use the main objects in your API immediately.
• A tutorial. Let me say this clearly: this is the most important thing you can do. Write a tutorial which goes through the different parts of your API in a logical order, making no assumptions about what the user knows. The tutorial should be as large as it has to be, taking up clearly defined chapters if necessary. Each section, or the complete piece, should show examples that build up into a working system, which covers a use case of your API. Any user who has taken the time to read and understand your tutorial, taking into account the burden of explanation remains entirely with the author, should be a near expert with your API and should be able to fully understand the previous three important documents (both overviews and the API).

Do this and you will be fine. Do not and you will frustrate and alienate part of your potential userbase.

Another relatively large month for cinema visits but, sadly, a fairly mixed bunch. Might as well begin:

Philip Seymour Hoffman deserved his oscar for his portrayal of writer Truman Capote. This film looks at the authors life around the time he was investigating and writing the greatest of his books, In Cold Blood. Capote is about a man obsessed with himself, his own greatness and ability, and the lengths he will go to in order to become immortalised. It’s a fascinating insight into the mind of one of the greatest writers ever, and thankfully it isn’t overly sugar coated.

Stay is an interesting film. It starts off as a fairly mainstream story about a psychiatrist (Ewan McGregor) who gets a suicidal patient, a young man who will kill himself on his 21st birthday which is only days away. From there we see a descent into madness, the lives of all concerned unravelling and being entwined with that of the patient. Arty, beautiful, but with a fairly poor ending, this film is worth watching just to have seen it. The tricks employed throughout are dazzling, the insanity permeating the film.

The thing about remakes is that you have to remake something that was pretty good, perhaps with a strong central premise, for it to be worthwhile. Anyone who can remember John Carpenter’s The Fog will know that this is not the case (B-movie horror fans, even you know it wasn’t great). A remake with poor CGI, dreadful acting, ghost lepers, and weak motivations that takes itself seriously just doesn’t cut it. From the awful soundtrack to the painful comic relief, this film is the epitome of formulaic modern horror. Avoid.

Sold as being from (some) of the writers of the Scary Movie films, Date Movie is exactly what you might expect: an adolescent spoof of recent romantic comedies, and teen flicks that focus on love. The thing it misses is humour. While there are moments (two) of hilarious, but utterly juvenile, laughs, for the most part this is a case of taking elements from other films and expecting them to be funny out of context. It doesn’t work like that, and the writers should know better.

Having now officially finished his stint as smug super-agent supreme, James Bond, Pierce Brosnan takes on an entirely different angle at the old killing game. In The Matador, Brosnan plays a washed out, dangerous, seedy, but ultimately lonely assassin, who happens to befriend a loser business man. The elements that bring them together are tenous, and the films finale awkward, but still the charm of the lead lets some of the better lines shine through. Enjoyable enough to watch, if nothing spectacular, Pierce has done a good job against type.

While Memoirs Of A Geisha has been out for a while, I only just saw it at the cinema so will include it here (I will, however, exclude Apocalypse Now Redux, which I also only just saw). This is a film of contrasts: beautifully shot, yet overblown; seemingly long, but only showing snippets of the character’s life; dramatic, yet turgidly dull. It’s not that it’s a bad film, it just doesn’t do or say anything particularly interesting: the central premise of loving a near stranger rings cold to the passion it attempts to portray.

The Ringer definitely grew out of a bad idea: something thinking that they’d like to make a film about rigging the Special Olympics. I have no real problem with the central premise, in so far as anyone is equally fair game for a pisstake, but the execution is somewhat offputting (and indecisive). Knoxville and cast spend half their time moralising that the other contestants are smarter and better than their stereotypes, and the other half saying that they are basically idiots. Couple this with the fact that the jokes never really get over repeating the initial idea, the film falls flat on its face.

Finally, from the makers of The Matrix (although not directed by them, or based on an original work by them or… what did they do again?), V For Vendetta is the overtly comic book look at a society where fascism has taken over Britain, and the rest of the world is in turmoil. Leaving aside the ridiculous British stereotypes (bad accents, Benny Hill, and pubs) and slightly cringeworthy finale, this story of an uncompromising freedom fighter is surprisingly good. I don’t want to say much about it, it’s not an action film as the trailers may make you believe, but it is worth seeing.

And the winner is… Stay, simply because it is a beautiful and complex film, arty without being arsey.

So, a bunch of people think that by “going naked” today that they can make the web better by promoting web standards, proper semantics and yadda-yadda. Now, I’m all for web standards and XHTML and all that, having been on the X Philes list since it started and generally encouraging standards, but this is a bloody silly idea.

Here are two scenarios for you, decide which is more likely:

1. A user stumbles on a site that is stripped of CSS and follows a link to the main Naked Day site, where they read all about the purpose (which isn’t actually explained in any detail) and say, “By George, I should be making my site better, like this great looking site!”.
2. A user stumbles on a site that is stripped of CSS and says, “By George, this site is either hideous or broken, best be going to another one that actually works”.

Sorry guys, but who is it you’re actually trying to reach? Either people already know about standards or not, and then either care or not. Making your site look crappy, even if perfectly usable won’t convince anyone. Just because it’s usable without stylesheets doesn’t mean people want to use it. You see that’s the side of usability that everyone seems to have forgotten for this idiocy: that you have to make the user want to use the site. If anything, this will have people running for the table-ridden sites that don’t look like they’re broken.

Here at Solitude, we appreciate the spirit of the day, really, but the implementation is broken; we’ll keep the clothing on, thanks.

I know people have developed some fairly clever systems for organising their priorities and tasks, but I’m still using post-it notes to organise (yes, it is a total nightmare). I’m looking for some system which is neither bureaucratic nor rigid.

Constraints:

• While I can see the point in organising to some extent (there’s no way I’d remember all that stuff without noting it down), I don’t want tied into dogma either. Just a simple way of doing things.
• Paper-based. I am not carrying around a PDA with me.
• Must be explainable in 60 seconds. If it takes longer than that then it’s probably far too complicated already.
• Update consolidation must be easy. That’s the real problem I have: a bunch of post-it notes that started with 5-10 items, and now have a handful each. There’s got to be an easy way of pulling together all the random items.

Got suggestions?

Living closer to the cinema (a 15 minute walk) has meant that this month has a massive eight films lined up.

Spielberg fills in the blanks after the infamous murder of the Israeli Olympic athletes two decades ago in his epic Munich. Focussing on the Mossad agents charged with vengeance on those responsible rather than the incident itself was the first error here. While we watch Eric Bana morph from struggling with his mission to becoming a paranoid but capable agent, we do not care; his inner turmoil is largely his own, motivated only by a flimsy patriotism which, self defeatingly, is gone in the end. The plot itself is entertaining, if a little plodding, but does nothing to communicate a message effectively to the viewer.

A Johnny Cash biopic was always going to feature music heavily, that’s a given. What is surprising is the impressive job that both Joaquin Phoenix and Reese Witherspoon do in the lead roles, allegedly providing the song vocals themselves. The film looks at Cash’s rise to stardom in the first act, but swiftly changes to his pursuit of his would-be wife, despite his drug abuse and family. Sure, there are more interesting parts of his life that could have been looked at, but putting them in a plot would have been haphazard. The writers took an obvious and easy route that, not without challenging moments, paints the lead character as the anti-hero many take him for. Walk The Line is fitting, if rose-tainted.

Hidden (Cache) is, in words that I can only assure you are weak, absolutely dire. Two hours of twaddle that had some of the pieces to make an interesting film (a stalker mailing video tapes of the lead character and the paranoia around that) but was, instead, resolutely dull. For the vast majority of the two hour length, nothing happens. When the few events of the film actually occur, you will be too bored rigid to care. How does the film wrap? Perhaps with the lead character learning a lesson? The stalker being shown justice, or even escaping in some cunning way? Maybe some dubious or deep moralising? The plot strands (any of them) being resolved? Nope. Just a five minute shot of people coming out of a building. Really. An instant place in my worst three movies of all time.

Expecting a chick flick, Derailed both shocked and surprised. Beginning as a story about a man having an affair with a beautiful and intelligent woman, it quickly spirals into a blackmail drama with a sting in the tail. Though the twist is predictable, it is nonetheless enjoyable. The cast, as a whole, put in a sterling performance, the film hampered only by an extra fifteen minutes that tidy things up a little too nicely.

Final Destination 3 is nothing but trashy, fun horror. The “plot”, gaping holes and all, features the same prophetic warning of imminent disaster as seen in the previous two parts followed by fate closing in on the survivors of the accident. Essentially the whole film is just the set-up for some incredibly gory and intricate death scenes. Awful but enjoyable, chewing gum cinema.

The journalists who helped bring down Senator McCarthy get their story told by George Clooney in black and white biopic Good Night, And Good Luck. Tightly focussed on the respected newsmen who fight a lengthy media war to get rid of the overbearing paranoia and witch hunts for communists that the Senator used to get into power, it rarely falters into the extraneous. Smart, short, perfectly paced: along with his previous directorial effort (Confessions Of A Dangerous Mind) Clooney shows he has style and flair, and a well-judged knowledge of the subject matter.

On the other hand, Lucky Number Slevin is all style and no substance. Sharp, witty and off the wall dialogue is lost in a movie that can’t back it up. The plot attempts to be intricately woven and clever but is, in fact, just badly cut. Repeat to self: putting scenes out of order and using revelatory flashbacks is a difficult plot device to get right. Memento understands this, Lucky Number Slevin does not. Obvious, occassionally amusing, and nothing special.

Finally, Aeon Flux is exactly how not to adapt from other media. While I cannot claim to have seen the MTV cartoon on which this film is based, a brief inspection of the film shows that there is clearly a well planned, long term plot and a detailed, intricate universe. For inexperienced hands to fit it all into this 90 minute travesty of an action film means that much of the material is handled in the most juvenile way; trampling over the ideas, rather than nurturing them. That is bad enough; to then further the awful telling by focussing in all the wrong places for bite-sized pieces of time is just unforgivable. Awful.

The winner for February? Good Night, And Good luck. While the Johnny Cash film is excellent and Derailed is solid if not for the final scenes, Clooney’s work barely misses a beat.