Archive for September, 2008

Interfaces first

Posted on September 30, 2008

Don’t write spec documents, throw away any you have near you, they’re next to useless anyway. It might seem like a hearsay to some but it’s true and deep down even the most most anal planner in all of us knows it. Two of the biggest reasons for this are:

  • size and scope: In order to address every aspect of your project a full specification document has to, well address every aspect of your project and it’s going to be huge as a result.
  • lack of vision: For most people relating what’s written on paper to a vision of a design in their heads is difficult if not impossible.

Loose documents don’t work well either, because leaving the obvious unsaid just leads to problems, chiefly not everything is obvious to everyone. The devil is in the details and avoiding them until the end of a project is just going to cause trouble.

“Why haven’t we implemented x, that should have been obvious!”

create the interfaces

Prototype the interfaces and use them as your spec. Working this way has so many benefits, try it once and I promise you’ll be converted. Before you write a single line of backend code, sit down and work out your interfaces. Build each screen, put all the buttons, fields and elements on the page

I normally start with index cards and write a few simple requirements for each screen or page – just a few simple sentences listing what the page is expected to achieve.

My next step is to turn those requirements into interfaces.

in HTML, not photoshop

Photoshop is great, but let’s face it it’s no better for trying to work out a functional interface prototype than some paper and a pencil. It’s very easy to focus on making things look pretty over making them functional and you risk missing something important out.

The best way to avoid both of these traps is to write your interfaces in HTML, mark them up semantically as they will be marked up in the release and use them as your working spec.

I know good design but I’m no designer

Another benefit of coding up your interfaces in HTML before you start writing code is you can hand them off to designers so they can make them look pretty as you’re working on making them work. I have a pretty basic idea of design principals and the tools – but I find it hard work. So with interface first development I don’t have to think about it.

let the testing begin

Another thing which is made infinitely easier with interface first development is functional testing, because your testers don’t have to wait for a release before they can start developing a test suite. You are using an automated test suite aren’t you? By generating interfaces as developers add functionality testers can already have been through the interfaces and written a whole series of failing tests.

updating later

The great thing about using HTML as your design and communication tool is that when it comes to making a change to a page you have the most up to date working copy there ready to modify in the form of your site. Just save the page, add the change to the HTML and you’ve got your interfaces ready for discussion and later implementation. What could be easier, faster or more clear for everyone?

it’s not a panacea

There have been times when I’ve been working with notoriously difficult individuals where nothing was going to satisfy. An exmaple that springs to mind is a multi month project where we produced an interface design early in the project. The design was a set of PDF images not HTML (see above), but the delivered product was a pixel perfect implementation of it. Only once the project was delivered was there any input on the design or functioning of the project – I’m not just talking things that a PDF can’t show you like what clicking a link looks like. I’m taking basic things like colours, layout and the size of elements!

Would a HTML mock up have made any difference, I actually doubt it. I take blame for miscommunication and resulting mistakes when it’s my fault but in this case even after the site was fully developed and deployed to a staging area for testing none of these issues were highlighted. It was only after the site was put into production that these “critical issues” were discovered.

Is it better?

Posted on September 29, 2008

After reading this post what Jamie said hit me as well:

This is when I realized how trained I was in the processes at my former workplaces. This email would have been delayed until it was perfect[...] After fixing this there would be another thing and then another thing. A 2-day project would drag on for a week of redesign, approval, and development[...] It’s one thing to read Getting Real [...] It’s another thing to actually practice the principles. [...] That part is trickier than you think.

I don’t think it’s just Jamie and I don’t think it’s just his former workplaces. We’re all trained to make excuses not to launch, it’s endemic in the culture of most organisations. We endlessly pay lip service to the principals of release early and release often, agreeing in principal
with the principals – but put very little of them into practice.

A manager’s role is to facilitate an organisation’s march towards better – all too often it’s a weak manager that needs constant input on projects and at the root it’s fear of inadequacy on their part that builds a culture of ass covering. It’s obvious that at 37 Signals they don’t suffer from being crippled organisationally when executive decisions need to be made but executives are absent. Their staff are trusted to make decisions and they’re empowered to release better features.

When your last change was ready to deploy, when it was better than what was there, did you release it? If not, how long did it take you to get from that point to actually releasing it and how many people had to give final approval?

Why not empower your staff with a simple test – Is it better than what we have? No flow charts, no organisational hierarchy; just a simple question.

Location services – must try harder

Posted on September 26, 2008

Location based services, another area where there is certainly a case to be made for someone to make it suck less and probably a number of successful application to build on it.

Why it sucks

Location services suck because it’s inherently hard to map the collection of information on the Internet to physical locations.

Most of it just wont map because it’s not about something physical.
It’s obvious, but true – most of the Internet isn’t about a place, or a thing that is likely to stay in one place. This post for example, or this blog’s homepage – neither are about anything specific. My house isn’t

It’s hard to map because language is imprecise, physical location isn’t.
When you’re looking for a nearby restaurant a blog post with a review of a restaurant in London probably won’t give you an address and probably won’t even link to a site that will. It’s become the job of search to try and link the post, a very difficult job – was the post about London, England; London in Ontario or one of the dozens of other Londons around the world. At best the search engine might be able to link the name with another URL that contains an address – but there are no guarantees the name is unique or the address is right.

Sending letters for physical addresses with an activation code is one approach Google has tried, I’m not sure how successful it’s been though – I haven’t noticed locations search has stopped sucking, so I assume it’s not the silver bullet.

Sucking less

How to go about fixing it? If I knew the answer I’d be coding the solution right now and wouldn’t be sitting her writing and thinking about it.

The rise of location aware internet devices
It’s inevitable, the rise of the iPhone, Andriod phones and other location away devices with Internet connections mean people are going to want to consume location based resources. Though they’re not the first phones on the market to do any of this, they’re game changing because they’re the first platforms that make it easy to consume and more importantly produce location based content.

The other key ingredient these platforms offer is a browser, not just a cut down browser – a real browser, with tabs and javascript and all the trimmings!

Like any good problem, this one can be solved with metadata!
We’ve got the consumers with their million plus iPhones, we’ve got the producers who all want to start geo tagging. The problem is how do we link the two and how do we make it easy? We’ve got a few standards for location tagging document, but no clear forerunner.

Suddenly it doesn’t suck anymore

Services for producers and users to announce and tie information to physical locations is going to be the catalyst that really makes local search and local information portals of all kinds take off. It won’t be long until someone comes along with a killer solution.

Weekend catchup

Posted on September 25, 2008

My weekend catchup reading list.

What I’m reading: 37 Signals, Defensive Design for the Web

Posted on

I’ve read the excellent Getting Real by 37 signals online and haven’t been disappointed by their Defensive Design for the Web. In the real world things go wrong and you can’t prevent every error, but you can handle them properly. It’s not just a book for coders or webdesginers either, I’d recommend it to anyone making decisions about site design, layout or functionality. The book covers topics from usability to copy writing using easy to follow, real world examples of websites getting it right, and other getting it wrong.

Defensive Design for the Web from amazon.com
Defensive Design for the Web from amazon.co.uk

Why are bookmarks so useless?

Posted on September 24, 2008

I have a real problem with bookmarks. Actually I have a few problems with bookmarks: There are too many, they’re a mess, they don’t make any sense and I can’t search them. Basically they’re a good idea, really badly implemented.

I have a list of bookmarks, I try to keep them organised but there are hundreds every few months I have to go through and throw some away. The clutter in my bookmarks also leads to bad habits. If it’s something I want to read later, I drag a link to my desktop or I put it in a read later folder. These quickly grow out of hand. Then I start getting protective and avoid saving links, dooming myself to searching for them again.

Lately, using Google Reader I’ve come up against another problem – I’m building a whole new set of bookmarks in the form of starred items, except these are completely separate from the rest of my browsing but I keep doing it because it’s easy and I can search them.

When it comes down to it my problem is basically simple, I can’t ever find anything again! It’s even worse if it’s something I’ve found via searches because it might be weeks or months later I try to find the page again and it’s likely that the Google’s index will have changed in that time. So my searching for something I’ve seen gets harder.

Bookmarking the page doesn’t usually make it easier, there is no frame of reference. Unless I’ve set the title to something useful a lot of the time I find it hard to find things again because lot of the time with hundreds to go through, or I’ve cleaned it out and it doesn’t exist anymore anyway.

I’ve tried delicious and other similar tools, and I like them, tagging my links makes them infinitely more searchable. But it doesn’t go quite far enough – it still has a feeling of permanence and exclusivity to it when I tag something and I don’t always want to share everything I tag.

The other problem with social bookmarking and tagging sites is they provide a tag for me, but no context. So days, weeks or months later unless I’ve tagged the site well I may or may not be able to find it. I thought I saw a site that indexed the links from delicious, but I seem to have lost it and can’t find it again(You see what I mean!).

What I really want to see is a site that lets me star or bookmark a page or RSS feed and I want it to index my little corner of the web.

A change of direction?

Posted on September 23, 2008

A few months ago we announced Citrus, a suite of tools we’d been developing for estate agents. Despite our bullish attitude to building and selling the application we’ve taken a step back over recent weeks and taken a long hard look at what it is we’re doing. The result of the look is a change of direction, back to some ideas we’ve had in the past about personal search, bookmarking and some location based services. It’s a bit too early to get into too much detail about what we’re planing but I wanted to take the time to give a bit of an explanation of why we’ve changed our minds. 

The market has changed, there is no doubt, but we know that. On reflection though we decided our assumptions were probably wrong. We knew there were not going to be a lot of new players entering the market but existing businesses probably aren’t going to want to change, software tools and they’re not going to want to part with money especially if they had already paid to have a site developed and especially if they’re being forced to lose people.

Then came the next blow to the project,  we were asked to shut down the only current user of our software. They’d decided to put their business on hold because of changes to the Spanish regulations and the current state of the market.  So now we were facing selling a product, in an unfriendly market without our evangelist. 

I’d also be lying if I said that we had generated the interest we’d hoped to generate, we didn’t. It goes without saying that had we generated that interest, or close to that interest we wouldn’t have had the moment of introspection and we wouldn’t have needed to take this difficult decision.

Integration testing in maven – With Maven, Cargo, httpunit and Selenium

Posted on September 22, 2008

I’ve been trying to figure this out for months, and thought it should have been simple. All I wanted to do was write a set of unit tests to test my java code, have them run whenever I hit test. Next I wanted to have a set of HTTP Unit, Selenium or similar tests run to test that the actual application is working when it’s built and deployed to a container using the cargo plugin.

I didn’t really want to have a separate project to do this because it seemed like a massive pain in the ass to maintain the whole thing. I didn’t see any reason why it shouldn’t be easy with Maven either – it does have a phase for integration-tests already.

My first try looked good to me:

 

...
<build>
    ...
    <plugins>
        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>**/integration/**</exclude>
                </excludes>
            </configuration>
            <executions>
                <execution>
                    <id>integrationtest</id>
                    <phase>integration-test</phase>
                    <goals>
                        <goal>test</goal>
                    </goals>
                    <configuration>
                        <excludes>
                            <exclude>none</exclude>
                        </excludes>
                        <includes>
                            <include>**/integration/**/*Test*.java</include>
                            <include>**/integration/**/*Test.java</include>
                            <include>**/integration/**/*TestCase.java</include>
                        </includes>
                    </configuration>
                </execution>
            </executions>
        </plugin>
        ...
    </plugins>
    ...
</build>
...

 

I tried to run the tests, but unfortunately when it gets to the second round of tests – which should run my integration tests – it runs the same sets of as it ran the first time. I tried adding the combine.children="append" attribute to the includes, and excludes but that didn’t work either. Finally I came across a source file XppDom, part of plexus which maven uses. XppDom allowed the combine.children attribute as well as another I haven’t seen mentioned anywhere else childMergeOverride. I added that instead and it worked!

 

...
<build>
    ...
    <plugins>
        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <configuration>
                <excludes>
                    <exclude>**/integration/**</exclude>
                </excludes>
            </configuration>
            <executions>
                <execution>
                    <id>integrationtest</id>
                    <phase>integration-test</phase>
                    <goals>
                        <goal>test</goal>
                    </goals>
                    <configuration>
                        <excludes childMergeOverride="true">
                            <exclude>none</exclude>
                        </excludes>
                        <includes childMergeOverride="true">
                            <include>**/integration/**/*Test*.java</include>
                            <include>**/integration/**/*Test.java</include>
                            <include>**/integration/**/*TestCase.java</include>
                        </includes>
                    </configuration>
                </execution>
            </executions>
        </plugin>
        ...
    </plugins>
    ...
</build>
...

 

 

Setting it up for Cargo

I’ve done this on a few projects, the first was a project that built a series of taglibs which are used across a number of applications. The release for the project is a jar so I have a separate test web-app structure in ${baseDir}/src/test/web-app. The code for generating this war looks like this:

 

...
<build>
    ...
    <plugins>
        ...
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
            <executions>
                <execution>
                    <id>generate-test-war</id>
                    <phase>pre-integration-test</phase>
                    <goals>
                        <goal>war</goal>
                    </goals>
                </execution>
            </executions>
            <configuration>
                <warSourceDirectory>${basedir}/src/test/webapp</warSourceDirectory>
                <warName>${project.artifactId}-test</warName>
                <webappDirectory>${basedir}/target/${project.artifactId}-test</webappDirectory>
                <primaryArtifact>false</primaryArtifact>
            </configuration>
        </plugin>
        ...
    </plugins>
    ...
</build>
...

 

During the pre-integration-test phase the above simple generates a test war. If you’re project is a web-app and it already generates a war you can skip the above as one will be generated for you already.

The next step for was then to get Cargo to deploy the application:

 

...
<build>
    ...
    <plugins>
        ...
        <plugin>
            <groupId>org.codehaus.cargo</groupId>
            <artifactId>cargo-maven2-plugin</artifactId>
            <configuration>
                <wait>false</wait>
                <container>
                    <containerId>tomcat5x</containerId>
                    <zipUrlInstaller>
                        <url>${integrationtests.tomcatURL}</url>
                        <installDir>${installDir}</installDir>
                    </zipUrlInstaller>
                    <output>
                        ${project.build.directory}/tomcat5x.log
                    </output>
                    <log>${project.build.directory}/cargo.log</log>
                </container>
                <configuration>
                    <home>
                        ${project.build.directory}/tomcat5x/container
                    </home>
                    <properties>
                        <cargo.logging>high</cargo.logging>
                        <cargo.servlet.port>8080</cargo.servlet.port>
                    </properties>
                </configuration>
            </configuration>
            <executions>
                <execution>
                    <id>start-container</id>
                    <phase>pre-integration-test</phase>
                    <goals>
                        <goal>start</goal>
                        <goal>deploy</goal>
                    </goals>
                    <configuration>
                        <wait>false</wait>
                        <deployer>
                            <deployables>
                                <deployable>
                                    <location>${basedir}/target/${project.artifactId}-test.war</location>
                                    <type>war</type>
                                    <pingURL>http://localhost:8080/${project.artifactId}-test/index.html</pingURL>
                                    <pingTimeout>300000</pingTimeout>
                                    <properties>
                                        <context>${project.artifactId}-test</context>
                                    </properties>
                                </deployable>
                            </deployables>
                        </deployer>
                    </configuration>
                </execution>
                <execution>
                    <id>stop-container</id>
                    <phase>post-integration-test</phase>
                    <goals>
                        <goal>stop</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
        ...
    </plugins>
    ...
</build>
...


Most of this is pretty self explanatory, I try to use parameters to configure as much as I can and try to maintain it in higher level POMs wherever appropriate. This is especially true for the tomcat URL which changes on a regular basis. The seem to post new releases and remove the older ones, and it can be a chore to keep up in multiple projects. You may want to look at the cargo plugin documentation, you can ignore some of what I’m doing above if you’re project’s default artifact (the one package creates) is a web-app. 

So there you have it, eventually I got there after a lot of digging. I’ve been pretty brief in my explanations and have assumed a fairly good understanding of maven. if you have any questions by all means leave a comment and I’ll do my best to make it clearer.

Related articles by Zemanta
Reblog this post [with Zemanta]