Surely REST isn't the travelling salesman does design?

Occasionally I run across things on the web, this time tweeted by Mark Baker (@distobj), that make me read them several times.  The link he tweeted is to this page on a Nokia API and in particular this section...

Biggest advantages noticed is that the API itself becomes the documentation of the API

• Without HATEOAS developers would get data, go to a documentation, and figure out how to build the next request

• With HATEOAS developers learn what are the available next actions

Either of these would get me firing you I think.  I'm a big fan of documentation and I'm a big fan of design.  What I'm not a big fan of is people who treat the design process as a series of abstract steps when the only thing that matters is the next step.

Lets be clear, having clear documentation available is important.  What would be poor would be two things:

1. Having to wait for someone to build an application before I can start writing a client for it
2. Having documentation that is some sort of 'mazy of twisty passages' where you only see one step ahead

This to me is at the heart of the death of design in IT, the lauding of everything as architecture and the massive chasm that appears to be developing between that and writing the code.  I'm repeatedly seeing approaches which are code centric rather than design centric and the entire history of IT tells us that this isn't the best way forwards.  Don't try me on the 'I just refactor' line as if that is an answer, spending 1 day thinking about a problem and planning out the solution (design) is worth 5 days of coding and 20 days of subsequent refactoring.

I'd really like a developer to be able to map out what they want to do, be able to read the documentation in one go and understand how they are going to deliver on the design.  I don't want a developer context switching between API, code and pseudo-design all the time and getting buried in the details.

This is part of my objection to REST, the lack of that up-front work before implementation - if I have separate client and service teams I don't want to run a waterfall project of 'service finishes, start client' and if those are two separate firms I want to be able to verify which one has screwed up rather than a continual cycle of 'its in the call response' and 'it was different yesterday'.  In other words I'd like people to plan for outcomes.  This doesn't mean not using REST for implementation it just means that the design stage is still important and documentation of the interface is an exchangeable artefact.  Now if the answer is that you have a Mock of the API up front and a webcrawler can extract the API documentation into a whole coherent model then all well and good.

Because the alternative is the travelling salesman problem.  If I don't know the route to get things done and am making a decision on the quickest way one node at a time then I'm really not looking at the efficiency of the end-to-end implementation just the easiest way to do the next step.

This current trend of code centric thinking is retarding enterprise IT and impacting the maintainability of REST (and other) solutions.  This isn't a question of there being a magic new way of working that means design isn't important (there isn't) its simply a question of design being continually undermined and discarded as an important part of the process.  Both of the scenarios outlined in the article are bad, neither represents good practice.  Choosing whether your manure sandwich is on a roll or a sub doesn't change the quality of the filling.

Think first, design first, publish first... then code.

Anti-Principles

Okay so everyone knows what a principle is, its a core concept that you are going to measure things about. I've seen projects littered with the buggers.

The problem is that there is another concept that is rarely listed, what are your anti-principles?

In the same way as Anti-Patterns give you pointers when its all gone wrong then Anti-Principles are the things that you will actively aim to avoid during the programme.

So in an SOA programme people will fire up principles of "Loose Coupling", "Clear Interfaces" and the like but they often won't list the Anti-Principles. These are often more important than the Principles. These are the things that indicate danger and disaster.

So what are good (bad?) SOA anti-principles?

Small return Values

This is where people have been used to Batch interface where returns are just codes and descriptions with reports being used to indicate problems. The sort of statement here is just return a code and description rather than returning a decent amount of data

Direct Calling

This anti-principle is all about where people just get a WSDL and consume it directly without any proxy or intermediary. Its programme suicide and it shouldn't be done

Interface Generation

This anti-principle says that you shouldn't generate your interfaces from code but should design them up front and make them explicit. So from an anti-principle perspective you are banning the "right-click generate WSDL" IDE approach to Web Service exposure.

No matter what the project you are doing you should think about your anti-principles as much as your principles. Think about what is bad practice as much as what is good practice. Make it clear, make it explicit.

Anti-Principles - making clear where people are going wrong.

Technorati Tags: SOA, Service Architecture

Why contracts are more important than designs

Following on from my last post on why IT evolution is a bad thing I'll go a stage further and say that far too much time is spent on designing the internals of elements of services and far too little on their externals. Some approaches indeed claim that working on those sorts of contracts is exactly what you shouldn't do as its much better for the contract to just be "what you do now" rather than having something fixed.

To my mind that view point is just like the fake-Agile people who don't document because they can't be arsed rather than because they've developed hugely high quality elements that are self-documenting. Its basically saying that everyone has to wait until the system is operable before you can say what it does. This is the equivalent of changing the requirements to fit the implementation.

Now I'm not saying that requirements don't change, and I'm not advocating waterfall, what I'm saying is that as a proportion of time allocated in an SOA programme the majority of the specification and design time should be focused on the contracts and interactions between services and the minority of time focused around the design of how those services meet those contracts. There are several reasons for this

1. Others rely on the contracts, not the design. The cost of getting these wrong is exponential based on the number of providers. With the contracts in place and correct then people can develop independently which significantly speeds up delivery times and decreases risk
2. Testing is based around the contracts not the design. The contract is the formal specification, its what the design has to meet and its this that should be used for all forms of testing
3. The design can change but still stay within the contract - this was the point of the last post

The reality however is that IT concentrates far too much on the design and coding of internals and far too little on ensuring the external interfaces are at least correct for a given period of time. Contracts can evolve, and I use the term deliberately, but most often older contracts will still be supported as people migrate to newer versions. This means that the contracts can have a significantly longer lifespan than the designs.

As people rush into design and deliberately choose approaches that require them to do as little as possible to formally separate areas and enable concurrent development and contractual guarentees they are just creating problems for themselves that professionals should avoid.

Contracts matter, designs are temporary.

Technorati Tags: SOA, Service Architecture

Why the hell do vendors not use version control properly

This is an appeal to everyone out there who is writing a product that is meant for an enterprise customer, you know the people with budgets and it applies to companies big and small.

When doing a project you normally have a lot of things to control

• Word docs
• Powerpoints
• Visio
• Requirements
• Code
• Test Cases
• Data models
  
• etc

The point is that its a lot of different things. What makes it easier to control things is a version control system. What makes it easier is if we can use one version control system to manage all these elements. What this means is that your tool needs to

• Store things in lots of different files, every object or important piece of information should have its own file
• Delegate version control to an external tool

There are two very very simple principles that I'm fed up seeing people screw up. Having one massive XML file that your tool "helpfully" manages is just rubbish. Not only does this mean that people can't share sections of this but it also means that structurally I can't set up my version control structures so one area has all of the requirements, docs and interface specifications all managed together. This is a very bad thing and it means your product isn't helping my programme.

The worst thing about this is that its much easier for a tool vendor to just say "version control is done by another tool, if you want a free one then subversion is great otherwise we integrate with most of the major providers". Having this elementary dumb decisions of single files is just a very very bad design decision and completely ignores how enterprises need to manage and adopt technologies.

I really don't understand people who pitch up with a tool that fails on this basic test of

"see that individual important element in your tool, can I manage that as an individual element and do a release of that without dragging other crap in"

If I'm creating a Use Case I want to version at the Use Case level, not at the repository level. If I'm creating at the Process level I want to version at the individual process level, not at the repository level. If I'm modelling a database I'd like to be able to version at the entity level not the whole schema level.

Code works like this, it would be mental to have a code versioning system that worked on every file as a clump. Yet this is what lots of packages and other tools do.

Its 2009 folks and it appears people are still building tools that can't match the capabilities of RCS let alone CVS or heaven forbid something from this millenia. So a quick summary

1. Expose your things as files at the lowest level of sensible granularity, this is normally the blobs or icons in your tool
2. Delegate versioning to an external product that does this stuff better. If you feel you have to include it then ship a copy of subversion.

That is all. Its that simple.

Technorati Tags: SOA, Service Architecture

Beware designers and other's prentending to be professionals

First off an admission, I'm an HCI guy and spent the first 6 years of my career working on front end thick-client high interactivity sort of interfaces where the accuracy of the interface was critical.

I then got into the Web world and learnt to distrust designers very quickly, for the simple reason that 95% of them were interested in designing a "pretty" interface rather than a functional interface. The two are very different beasts. Designers are often in the WILI (Well I like it) camp of design rather than the KISS camp. They love putting graphics onto sites and having complex interfaces that "surprise" their users.

Today I read this

“Google has momentum, and its leadership found a path that works very well. When I joined, I thought there was potential to help the company change course in its design direction. But I learned that Google had set its course long before I arrived.”

Which summed up for me the mentality of most designers I've worked with. Namely that no matter how good, and especially clean, the design is and how successful it is with the users then a designer will want to take you in a different "direction".

At the heart of the issue is one of training, most designers are good at designing static pages but are not well versed in HCI, human psychology, ergonomics or other scientific disciplines around how people interact with systems. This makes them amateurs but unfortunately ones who are perceived to have a differentiated skill, mainly because most of the time their designs are presented on paper, a medium in which they are very strong.

This is a pretty common piece around IT, architects who lay claim to oversight in areas where they don't understand the technology or business, business folks who know that a website is "just Excel scaled up" and database guys who know how to write code because "its all about the data".

These are not well meaning amateurs, they are professionals working in the wrong place at the wrong time and in the wrong way.

If you are working with a designer here is a top tip.

Get them to create a page template, not a full page, one which has the corner pieces, fonts et al all defined in a template. Then turn that template into CSS and use it on the pages that you create. You'll normally get a nice clean design feel and consistency but the designer won't like it because its all too consistent and you didn't implement a photoshop picture.

But your users will thank you.

Technorati Tags: SOA, Service Architecture

One Service many interfaces

I'm doing some departmental re-org stuff at the moment and its made me really believe in the difference between the service and its interface. Way back in 2000 I worked on a project and developed a framework (who didn't in 2000) that allowed you to have multiple different interfaces on the same back-end service. The reason for this was that different clients needed to see different subsets of capabilities and rather than showing everyone a great big interface with everything on it, which would be complicated, it seemed simpler to just separate the interface from the service.

Doing the business bit has made me really strongly realise how important it is to keep them apart. Right now I've effectively got four different groups who need to interface to this one business service.

Now the core of the service is the same for everyone, they all want basically the same thing. The difference comes in exactly how they want to interact with it and the specifics of the capabilities that they will use. This means four independent sets of external KPIs (remember to always think of the consumer when designing service descriptions) and four semi-independent sets of capabilities. By semi-independent I mean that they are in fact strongly linked but the mode of interaction is slightly different in each case.

Now if you were building the code for this you might be thinking of four independent services that shared information together. The problem is that this means that you have disjoint processes as the reality is that one of the major KPIs for the service is that you are linking properly with all the other groups.

Sometimes you will build the interface as just that, an interface, other times it will be a lightweight façade that might do some process or data manipulation work, on a very few occasions it might be something heavier weight but still using the same underlying base service.

The other technical view would be the "sod the users" and just have one interface. The trouble is that this just means that it will be rubbish to use for everyone and it will in fact be harder to manage because that doesn't represent the way that the world actually operates.

So what I've got is a service description that describes what the service does and then I'm building four service interfaces (which are to all intents and purposes service descriptions) on how it will interact and be measured by the four external parties. This means that from a catalogue perspective I have five services, from a consumer perspective they are all getting the service that they want and from my perspective I'm getting the consistent management and centralised governance that I need.

Everyone ends up happy and the amount of duplicated work is reduced. So keep your interfaces independent of your service.

Technorati Tags: SOA, Service Architecture

Did Borland destroy design?

At JavaOne I tend to focus on the real world case studies rather than the vendor pitches or the latest shiny library. At a few of these when they talked about lessons learnt the old "wish we'd done more design/analysis" came up. Wandering around the floor I also noticed that not only were there a lot less companies than years gone by, admittedly this isn't a bad thing given the "buy our EJB container" stuff that used to be there, I also noticed that the amount of people talking about "design" and "analysis" on the floor was also incredibly low.

Now I know that software goes in cycles but this has to be one of the worst eras in software for design support and indeed design championing. So it got me wondering, what killed design? Back in 2003 (only 5 years ago) design was almost at its peak with Oracle, IBM and others all competing to demonstrate their design credentials. Back then however the question was largely about what Borland would do with TogetherJ.

Now there were other things around (and others have come on since) but at the time TogetherJ stood out, it had brilliant round-trip engineering, it had a fantastic quality metrics package and generally just helped you get your job done. They even listened to feature requests. Peter Coad dropped in to hear us vent (only slightly) about how the network license manager wasn't any good for us because we travelled quite a bit and couldn't use Together on the planes. What we'd like we said would be the ability to "check-out" a license so we could use it on the plane and on client sites while we sorted network access out. The answer? "I haven't heard that use case before but its a good one, I'll get back to you". The result? The next version allowed you to check out the licenses.

Then at the end of 2002 Borland bought TogetherSoft (the company that made Together) and.... well basically nothing. From that point on Together went from something that almost everyone I knew used to something that was used by practically nobody. Sure it took a few years for the software to become out of date but it happened and as there had been no really new features added to it no-one upgraded.

This left the field down to small players like Enterprise Architect by Sparx systems and MagicDraw and the beast that was Rational and became the even bigger IBM Rational. Back then Rational had one of the all time dogs of a product Rational XDE it was awful in comparison with TogetherJ, XDE was practically a one package project killing machine.

Now fair play to IBM, since then they've dumbed the whole ethos of XDE and built a pretty good new stack, its probably the strongest one out there today (IMO) if you are building large scale enterprise apps.

Clearly design hasn't gone away and remains as important as ever. Its back to (drum roll please) The Mythical Man Month and the fact that thought is the hard part not the coding or technology part. Design tools help with the thought part.

Now Borland may not have destroyed design but they certainly removed one of the most innovative companies in the market from play. Its sad to see JavaOne and the Java Community in general focusing on code syntax over full professional solutions.

On the plus side this current fad could completely screw up Enterprise IT infrastructures thus meaning that people who actually concentrate on the important things over the technology will have yet another mess to clean up after.

Technorati Tags: Java