I had the pleasure of hearing a talk by Stewart Baird today, and I liked one of his ideas so much I thought I’d mention it here.

Object-relational mappers, IoC, ESBs, REST etc are all a big deal when you’re introducing them to teams or working with contractors who haven’t used them before.

To explain how it all fits together, you should create an architectural example — a reference system that implements a single, simple behaviour. To be effective, it should:

• Be end-to-end. It should demonstrate how events and data flow from the user interface through to the database and back, including any and all services in between.
• Be checked into source control. Publish it alongside the production code so everyone can see it.
• Lead your production code. When you introduce a new component — e.g. a distributed cache — add it to the architectural example first, before rolling it out to your main system.

It’s always nice if you can explore and see everything working for yourself. An architectural example can help explain new topics to less-experienced developers, and provide a nice reference of how you want to see things implemented in future.