Computer manuals

I recently ordered a copy of OS/2 2.1 for Windows on the Internet swap meet know as eBay.  I have been playing around with virtual machines quite a bit, since I did the Thirsty Developer Podcast interview on Hyper-V with my pal Beth Humphreys (AKA Server Girl).  When I saw this particular version of OS/2 I could not pass up the chance to get it.

When the box came in the mail it was quite heavy, I figured I got my money’s worth on the $10 shipping and handling charge, because most of it actually went to the cost of shipping.  When I opened the box I quickly figured out why it was so heavy.  The seller had included everything that came with the original box including the card for the complimentary issue of Inside OS/2 journal by The Cobb Group (which I doubt I will get if I send in the card).  Of course this also included the 2 hefty sized manuals: Installation Guide and Using the Operating System as well as a bunch of smaller supplementary manuals for things like the printer drivers, video drivers and event one dedicated to understanding the special edition (the for Windows part of the title).

Flipping through the manuals got me thinking about how manuals have changed over the years.  The most obvious change is that many software applications don’t ship with manuals any more.  Even the software applications that do ship with manuals have dramatically slimmed down the size of the manuals.  Even if you get a manual with your software, it will probably not spend the 183 pages that the OS/2 manual does on just installing the software (including 36 pages dedicated to the installation of the software on dual boot systems).

There are several things that have caused the dramatic reduction in software manuals:

Web Pages –  The Internet was around when that version of OS/2 shipped, but it was mainly an academic network that connected colleges and universities and some technology oriented companies.  Shortly after that operating system shipped we saw an explosion of what most people consider the Internet – web pages.  Software companies eventually started using it to store and deliver their documentation.  Lots of motivation for this, but cost was a primary driver.

Books replaced manualsO’Rielly publishes a very popular series of books called The Missing Manual that they call “the book that should have been in the box”.  Many times a book can be much more valuable than a software manual for learning a new product.  Looking for a manual?  Maybe you should try a book instead.

Documentation became integrated with the application – Dedicated electronic help files and readme.txt files were the start of this.  The original readme.txt file was a necessity of how software was developed and shipped.  You could literally update that file minutes before the disk was created, as opposed to software manuals that had lead time to print and ship to have them ready for packaging.  So that file contained the latest and greatest information, which included information about errors in the manuals.  Modern applications provide context sensitive help and “show me” type functionality that absolutely blows away the printed word.

People became used to software – Early software manuals spent a lot of time explaining complex concepts to end users like “how to use a mouse” and “what is a window”.  I am not poking fun at this, it was very necessary at the time because people where making a leap from a character based system to a graphical system or (maybe even more common) from no computer to a computer.  But you can assume that if you use a common metaphor, then most of your users will quickly figure out how to use your interface.

How many manuals do you have?

If you are like me, you have a drawer in your house that is dedicated to manuals that ship with the various products that you buy (I am talking about all manuals, not just computer manuals).  My drawer is so full of manuals that I am about to spill into a second drawer.  Showing my OCD streak, I will never throw away a manual for something I still own.  I have not referred to the manual for the Pioneer SX2300 receiver that I bought in 1988 in 20 years, but you never know when it will come in handy (even though I only turn it on a couple of times a year).  Even though I have more than 100 manuals, I can’t seem to find any software manuals other than the ones that I got with my circa 1992 Operating System.


Crayons and Creativity

On the last episode of The Thirsty Developer podcast Dave and I did an interview with Josh Holmes and Mike Labriola (listen to the MP3).  I casually mentioned a theory that I have had for a number of years, so I thought I would take a moment to share it.  My theory is that how creative you are is directly proportional to the number of crayons that you had as a kid.  My theory is the more crayons that you had the more creative you are.  Conversely the fewer crayons you had, the less creative you are.

I don’t have any scientific basis for this, but I have years of anecdotal evidence.  My anecdotal evidence is generally me meeting a very creative person and asking them how many crayons they had as a kid.  The answer almost always comes back as “the big box of 64, you know the one with the sharpener on the back”.  Several times I have met people that owned more than one box of 64 crayons (they must have used up all the burnt umber in the first box and needed the second).  A couple people have even mentioned that there is a box of 128 crayons that exists, so there must be some really creative types out there!

My story

I am not a very creative person.  Part of the reason with me coming up with this theory is that I did not have a lot of crayons growing up.  I joke sometimes that my mom only bought me a box of four crayons (red, yellow, blue and black), but the reality is that I think it was actually a box of eight.  I do remember not being able to color any pilgrims in gray outfits in my Thanksgiving project in first grade (I tried to color with the black very lightly to make it seem like gray, but it did not work out so well).  I do remember the girl sitting next to me mocking me with “Which color gray should I use; I have so many of them”.  I got my revenge when she hurt her arm trying to lift that huge box of crayons one day.  🙂

I was in college when I noticed the correlation between the creative people around me and the number of crayons they had as a kid.  That is when I started polling people around me and gathering my sample data.  My close friends in college got so sick of the poll that they actually bought me a box of 72 crayons just to shut me up (I still have that box of crayons and have used it a couple of times over the years).

Was it the crayons?  I don’t think so..

I do buy my kids the big box of crayons just in case, but I don’t think just owning the crayons will make you creative.  As with all things there is some natural talent that you either have or do not have.  I think that most of your creativity comes from your interest in doing creative things and investing the time in it (it is a lot easier to invest the time as a child).  Also it does not have to be crayons, Lego works well also.  Personally I am going to try and spend some times doing more creative things in an attempt to overcome those years of not having a lot of crayons to chose from.

Architecture by Baseball: Jargon


This is the sixth in a series of articles about how we can learn about software architecture by studying and comparing it to the sport of Baseball.  This series was inspired by the book Management by Baseball.

Baseball Jargon

Last Saturday I watched a baseball game between the Milwaukee Brewers and the Cincinnati Reds.  I noticed that the announcers used a lot of colorful jargon in describing the action that was playing out on the field.  Baseball has built up an interesting language of its own over the years.  Some of my favorites are:


Ducks on the Pond – a term used to describe when there are runners on base, but usually stated when the bases are loaded.


Can of Corn – a term used to describe a pop-up or a fly out that is easily caught by an outfielder.  The term comes from a device that grocers used to grab canned goods that were located on top shelves in their stores.  This device allowed them to quickly and easily grab these cans, without having to stretch or get a ladder.  Of course the term does not translate to modern grocery stores.


Payoff Pitch – a term used to describe a pitch thrown with a full count (3 balls and 2 strikes).  The term is usually used when there are 2 outs or when the pitch could have a large outcome on the game (like bases loaded).  A strikeout could get the pitcher out of the tight situation; a hit could lose the game for him.


Murderer’s Row – A reference to the 1927 New York Yankees, who had several of the game’s best hitters in their lineup.  In later years, it has been applied to other teams who had similar lineups stacked with great batters.


No-no – a term used to describe a no-hitter.  This is a reference to the scorecard: No runs, no hits.  The no-hitter is one of the best accomplishments a pitcher can achieve (the record for career no-hitters is currently 7 over a 27 year career).  The no-no is only over-shadowed by a perfect game, which does not have a cool jargon associated with it.


Jam – a term with several meanings (you see this a lot in baseball Jargon).  It can mean a pitch that is far enough inside that the batter cannot get a full swing.  It can also mean when a situation where the pitcher is in trouble ala “Smith is in a jam”, generally there are runners in scoring position with less than 2 outs.  And finally it can mean when the baseball are loaded (but sometimes the bases are juiced instead of jammed – another term that can mean the same thing).


What I found really interesting is that none of these terms are actually defined anywhere in the official baseball rules.  If you were a new fan, you would have to pick up these terms by asking people when they meant, or by listening to the announcers and inferring what the term meant by looking at the situation.  You would doubtless be confused by the overloading of terms like Jam and by having more than one term applied to the same situation:  Bases can be jammed, juiced and ducks on the pond all at the same time. 

Architecture Jargon

In software architecture we have our own jargon as well – lots of it!  Some days it seems that there are teams of people sitting in a room creating more jargon.  A couple of my favorites are:


Polymorphic – an OO Concept (OO is another Jargon) that allows the use an operator or function in different ways for different set of inputs given.  I will never forget someone telling me, “I had to re-work the code to make it more polymorphic”.  I had no idea what he did to make it more polymorphic, but he seemed happy about it.


Service(s) – As an industry we have become service happy, but without a good definition of what a service is.  Most commonly when people say “service” they assume that you mean a SOAP based web service that uses XML serialization and http as a transport, as opposed to something more abstract.  Because the terms are so overloaded, you should always ask “What do you mean by service?”.


Separation of Concerns – architecting and implementing your software in such a way that there is little to no overlap in functionality.  Back in the day we used to just call that “good code”.


MVC, COM, SOA, etc – There are a veritable soup of Three Letter Acronyms (TLAs) that we use and reuse in discussions.  There are literally too many to keep track of.


As an architect, we are invested in this jargon and surrounded by it on a day to day basis, so much so that it actually becomes part of our natural language.  But the obvious thing to point out is that many people that we will work with are not software architects and may not even be in technology at all.  Note:  If you are a software architect who works in industry and you don’t spend time with non-technology folks, you are doing something wrong.


As software architects we have to be cognizant of the fact that our business partners and customers do not speak the same language as we do.  We also have to change our behavior to account for this.  Here are some of the things that I have seen successful to bridge this language gap:


Make it about the business and not the technology – when you are having a conversation with your business partners and customers you should not be focused on the technology, but on what the business outcome will be.  There are exceptions to this of course:  Occasionally there are technologies that your business asks for by name like AJAX as in “We need to get some AJAX in our websites now”.


Don’t use the Jargon – Avoid the 3 letter acronyms and words like polymorphism.  They are necessary to deliver the software, but not to understand what the software does.


When Jargon slips out, explain it – If you are in a meeting and you hear SOA, just pause for a second and explain that “SOA is Service Oriented Architecture and it is a technique for building the application that makes it easier for other companies to use our software and hopefully makes it easier to maintain”.  Be careful to not be condescending or over promise what the technology can do.


Architecture By Baseball: The Managers


This is the fifth in a series of blog posts about how we can learn about software architecture by studying and comparing it to the sport of Baseball.  This series was inspired by the book Management by Baseball.


The last post in this series was called “Architecture By Baseball: Coaches“, where I talked about how the software architect can work better with the development team by emulating some of the things that a baseball coach does.  Baseball is a little different than other sports that have a Head Coach, in baseball the team leader is the manger.  Like the rest of the coaching staff, he wears the team uniform.  The manager extra responsibility of thinking tactically and strategically during the game and throughout the season.

Tactical during the game

When a player comes up to bat and there are men on base, the manager will often times give the batter instructions about how he is supposed to bat.  If it is a close game with a speedy runner on board, he may be instruction to bunt (called a sacrifice), rather than try to hit safely.  The manager is giving up an out in order to advance the base runner (this is a very tactical move).  Similarly, the manager may give the runner on base the “steal” or the “hold” sign or the “green light” to steal if they feel comfortable doing so.  These choices are not as obvious as they may seem, the manager may chose to give not have the base runner the steal sign even if he is very good at stealing because it might prematurely end the inning.  Nothing is worse than taking the bat out of your best players’ hands by ending the inning on a failed steal attempt.

Strategic during the game

The manager must also think strategically during the course of the game.  The strategic decisions start actually before the game begins, when the manager fills out the line-up card.  The line-up card is the list of 9 players (or 10 players in American League Baseball) that will start the game and what positions that they play.  There are a lot of factors that play into the line-up cards on any given day: the opposing pitcher, the historic match-ups, etc.  As the game goes on, there a limited number of players available to the manager during the game for substitutions (25 total players for most of the season and up to 40 for the last month of the season).  The manager must make sure that the best players are on the field at any given time, but they cannot replace players constantly during the game, because unlike many other sports, once a player leaves a baseball game they can not return.  As the game goes on the manager must know when to replace players for fresh players or specialist (pinch runners who are fast, or players who are better at defense).

Strategic beyond the game

Baseball has a very long season with many games (more than twice as many games as most other sports).  The manager must remember this as they are making decisions.  The manager must make sure to give most players a day off here and there throughout the season (there are a few super human players that never need a day off).  The manager must also be careful to not over use the starting pitchers or the relief pitchers during a game, as it can be costly to make the wrong decision.

Software Architects: the balance between strategic and tactical

Like the manager making the scorecard, the architect must make a lot of decisions before the game (or construction) even begins.  Scope is negotiated, technologies selected and proof of concepts identified and executed.  Once the work actually begins, there are dozens of tactical decisions that must be made, but the strategic goals needs to be assessed.  Communication is very key as these decisions are being made.  The manager in baseball has to give signals to the batter, catcher or base runner.  The software architect also has to communicate to the team members effectively so they understand what to do tactically, but he also needs to impart the strategic thought as well (so actually we have it tougher than the baseball manager).   You also have to get the most out of the development team (even if they don’t report to you directly).  There is a great quote by one of my favorite baseball managers that talk about this:



I don’t think a manager should be judged by whether he wins the pennant, but by whether he gets the most out of the twenty-five men he’s been given. – Chuck Tanner

There is no book in baseball or software architecture

Many of the tactical decisions that I talked about have “conventional wisdom” answers to them.  For example, man on first with 0 or 1 outs and the pitcher up to bat, the pitcher should bunt.  This style of management is called “by the book”, which is a reference to a mythical set of rules that contain the answers to all situations.  You can imagine the software architecture equivalent.  If it is a function that is needed by more than one platform, or is called by 3 or more applications, it must be implemented as a SOAP Web Service.  That may apply is many or even most situations, but there is no book of rules to follow in software architecture.  There is another quote that fits this notion as well:



“The Book is nothing but a piece of garbage. My book is me.” – Chuck Tanner

Architecture By Baseball: Coaches

This is the fourth in a series of blog posts about how we can learn about software architecture by studying and comparing it to the sport of Baseball.  This series was inspired by the book Management by Baseball.

Coaches in baseball are unique in a couple of ways compared to the coaches in other sports.  One of the most obvious differences is that in baseball, the coaches actually wear the team uniform.  I personally cannot think of another sport where this is the case.  In some other sports the coaches actually have to comply with a dress code that is vastly different than the players (I think it is the NBA that requires the coaches to wear coat and tie when they are at court side).  Not only do the coaches in baseball wear the team uniform, but they are assigned a number just like the players on the field.  The coach is really a part of the team.

Another key difference between coaches in baseball and coaches in other sports is that two of the coaches in baseball are actually allowed on the field of play during the game.  On the first base and third base lines there are two coach’s boxes where the team can choose to have a coach positioned during the game. 

There is a distinction between this and other sports that allow coaches on the sidelines (such as soccer, football and basketball).  When a coach is on the sidelines in those sports, they are totally out of the field of play.  A ball that leaves the field of play is dead.  In baseball the foul territory where the coaches stand is still in play, so a player can catch a foul ball in the coaches box and the batter will be out.  A ball can be overthrown during a play and hit a coach, interfering with the play; there are even special rules that govern when this happens – which is not very often, because the coaches are usually pretty good about getting out of the way.

The coaches in baseball are literally feet away from the action and are able to interact with the players in a deep and meaningful way.  When a player reaches first base or third base safely the coach can give him encouragement and intelligence about how the pitcher is delivering the ball to the plate.  This can help the player decide if this is a good time to attempt to steal a base or take only a short lead off of the bag (to avoid a pickoff move).

The third base coach is an integral part of the action when there is a man on base and there is a ball hit deep into the gap or down the lines in the outfield.  As the runner on the base is rounding third a split second decision has to be made to send the runner to home or to have him hold up on third base.  The player is in the worst position to make this decision, as his back is to the outfield.  The third base coach is the one who makes the decision to send the runner or not.  If you have ever been to a game in person, nothing is more dramatic that seeing the third base coach swing his arm wildly, followed by a close play at the plate.

So what can we as software architects learn from the coaches in baseball?

Wear the Uniform – Often times I see people make too much of a distinction between the architect and the developers who are working on a software development project.  This can manifest itself in a lot of ways, and many of them are bad.  The role of the architect is different than the role of the developer, but they should be seen as one cohesive team.  This statement applies equally well to the designers, testers, DBAs, server tech and project managers on the team as well.

Be a part of the action – Architects are sometimes referred to as Ivory Tower dwellers.  Sometimes this is meant as a joke, sometimes is a half-joke and other times it is just downright true.  As an architect we should strive to be as close to the field of play as possible.  The perception when you are away from the field of play is very skewed.  Get out of the Ivory Tower (maybe press box is a better analogy) and get into the coach’s box.

Be a coach – One of the things that I did not note in particular when talking about the coaches is that most of them are former professional ball players themselves (I don’t think that is unique to baseball coaches).  They bring with them years of experience that they can impart to the players them are coaching.  Most of us who carry architect in our title were at one time developers ourselves and as a result, we carry with us many years of experience.  In addition to architecting the application, we can make the team more successful by sharing our knowledge with the team. 


Software Development Meme (or tag I am next)

Josh Holmes called me out me in the latest round of questions going around the blog world.  This one is interesting, because it has the blogger answer questions about how they got started in software development.  Here is the current stack trace:

Michael Eaton (post) -> Sarah Dutkiewicz (post) -> Jeff Blankenburg (post) -> Josh Holmes (post) -> me (answers below)

How old were you when you started programming?

This one is tough to answer, because I actually started twice.  When I was 12 years old my friend Jim got a Commodore Vic 20 and I used to “program” on it.  It mainly consisted of copied programs from the back of the computer magazines and sophisticated programs like:

10 print “My name is Larry”
20 goto 10

I lost interest in programming after a few months, mainly because we could never get any of those programs in the magazines to really work correctly.  Or it also could have been all that Men At Work that I listened to.

The second time around I was in college and I was 20 years old and got started because of a required class in college.  I went to school to study photojournalism, but had to take 2610 – Intro to business computers.  I was scared to death to take a computer class, I figured I had to get an A in every other class that semester to make up for the D I was going to get in that class.  Fortunately I had an awesome professor, Tom Marshall, who was a Phd student at the time, but now teaches at Auburn University.  Tom got me totally hooked on the computer / information technology industry and eventually into programming.

What was your first language?

BASIC and then COBOL

What was the first real program you wrote?

My first inclination was to answer with a program I wrote when I was out of college, because that is the first time most of us write “real” programs, right?  But I am actually going to answer this with some programs that I wrote my senior year in college.  I went to the University of North Texas and they had a great program for Management Information Systems (although they called it BCIS).  Their program was geared to teach real world skills, and they even had you writing on real mainframe systems.  Those also geared their curriculum towards real world problems and techniques to solve them.  The killer course back them was the database course, taught by Dr. Vanecek.  After 3 or 4 grueling projects where there was a “right answer” (you were trying to write programs that produced an exact result), everything was take off the table and you had to build an entire system in 3 weeks (while taking 3 or 4 other classes).  I learned a lot about time management in those 3 weeks.

What languages have you used since you started programming?

BASIC, COBOL, JCL, ADABAS Natural, DYL280, REXX, Smalltalk, Visual Basic (classic and .NET), Javascript, C, C#

What was your first professional programming gig?

My first job out of college was working for Mobil Oil at their data center in Dallas, TX.  It was a neat first job because I actually worked for the data center and not on business applications.  I got a real understanding of the operations side of the house that people who have only worked as programmers never get to see.  Also I was one of the few developers that worked there, most people were systems programmers.  So I got to write a lot of code for neat projects like replacing a quarter of a million 3480 tape cartridges, consolidating 2 data centers and performing disaster recovery tests (sometimes the tests are more complicated than the real disasters).

If you knew then what you know now, would you have started programming?

Yes I would, but I would do a couple of things differently.  I will tell you what one of those is in an upcoming blog post (I was already working on it before I got called out).

If there is one thing you learned along the way that you would tell new developers, what would it be?

I have used this line (or one similar to it) for over 10 years when I mentor people new to the Industry:  “Nobody ever became CIO by just writing code”.  If you love to write code and that is all you ever want to do, please write code and perfect your craft (the world needs many, many more good developers).  If you have other aspirations, you need to diversify.  Learn about the database, learn about the infrastructure, learn about project management (I shutter when I say that).

What’s the most fun you’ve ever had … programming?

In 1996-1998 I worked for Compaq Computers in Houston, TX.  This was a different time in the industry than it is now, hardware still ruled.  While I was there we shocked the industry by releasing the first desktop machine that was priced below $1000 (and it did not come with a monitor).  I worked on a project to allow consumers to configure and buy computers in the retail stores.  We literally put the whole thing together in less than 6 months from bar napkin to full role out. I did a little of everything on that project : hacked database tables at night, troubleshot the Office Depot DNS servers (while in a store), created a caching system for images with ActiveX (along with J Sawyer) and even spray painted the prototype kiosk in my garage. 

I did not do a whole lot of programming on the project, my role was what we would now call a technical architect.  But I will never forget debugging some code on a Sunday morning so I could get the whole thing into production before I boarded a plane to New York for the press conference on Monday morning.  The marketing people were calling me and saying “they are boarding the plane right now”, I told them I would catch the next flight.  They told me 26 hours later after the whole thing was working that they thought I was seriously ditching them.

Who am I Calling Out?

I had a fun time answering these questions, so I would like to pass the meme on to the next round of folks.  Looking forward to hearing from:

Dan Rigsby
Dave Bost
Brian Moore (post)
Damon Payne (post)
Chris Pietschmann (post)
Angela Binkowski (post)

Updated (6/10) The list was updated to include links to response posts.

Twictionary

Twitter Logo

Update on 5/25: Added a couple of new terms to the Twictinary and fixed a broken image (thanks KeVron).

I like the Twitter platform a lot.  I have the very boring handle of @larryclarkin if you would like to add me to your follow list.  My creativity was at an all time low when I picked the handle, but I just tell people that I wanted to be easy to find as opposed to admitting that I have yet to come up with a cool handle to use on the Internet.

If you are not familiar with Twitter, it is a social network built around micro-blogging that is a great example of software + services with multiple clients that implements RESTful services on an Internet scale.  You can also describe it as an Instant Messaging system that all your friends (and even perfect strangers) can ease drop on the conversations.

It is not quite a verb yet…

I was recording a podcast today and the person I was interviewing dropped google (the verb) in the conversation.  Of course he meant “search”, but the word google has become synonymous with the word search (note:  Google does not want you to use their proper noun as a verb unless you are talking about their proper noun). 

I started thinking that when we as a society create new words around a platform, then that is a sure sign that it has taken hold.  Google (the verb) is probably the most widely accepted example of this, but Twitter has created a whole new set of words itself.  So I figured I would put together a Twitter Dictionary (or Twictionary).  This is just my quick stab at it, let me know if you have found any that I have missed:

Tweet– The < 140 character message that is sent out as part of your feed.  Proper usage: "I sent that out in a Tweet today”.

Tweoples – A reference to the twitter users that are following you.  This is the Twitter version of the term “peoples”.

Tweeps – A slang version of the term Tweoples and it is the Twitter version of the term “peeps”.  Proper usage: “Good night my Tweeps”.

DM – An acronym for “Direct Message” a Twitter feature that allows you to send a message to one Tweep that will not appear in the public timeline or the feed or either the sender or receiver (a private message).  Usage: “DM me the root password to the server”.

Twittercon – The square picture (73 x 73 or smaller) picture that you associate with your account (or if you are lame the default picture that Twitter provides you).  Proper Usage: “my smoking obama twittercon is finally going to pay off” – as seen in the feed of @KeVroN in reference to his Twittercon:

Kevin

Twitterdiction – a prediction that is made in the form of a Tweet.

dWittering – The act of sending a tweet out when you are intoxicated.  This act is often filled with regret and or shame when the tweet or tweets are seen the next day.  This can also be considered the SMS version of “Drunk Dialing”.  Special credit goes to @joshholmes for first pointing out this term to me and for perfecting the art of dwittering.

Ninja Tweet – The act of sending a tweet about someone without their knowledge (or consent), usually why you are talking to them (coined by Denny Boynton in his post on Twitter and the new social).

Cross Slide Scripting (XSS) – the act of Twittering/Tweeting to the speaker so his computer displays insults about the talk, DURING the talk (coined by @PHPTek during the PHP|Tek 2008 conference)

Architecture By Baseball: Ground Rules

This is the third in a series of blog posts about how we can learn about software architecture by studying and comparing it to the sport of Baseball.  This series was inspired by the book Management by Baseball.

One of the most interesting aspects of baseball is that it is the only sport where the field of play varies so widely.  Most sports have a very uniform field of play that does not vary from stadium to stadium (a football field is always 100 yards long and a basketball rim is always 10 feet above the floor).  One of the reasons I like baseball so much is the charm that the ballparks have with their unique dimensions.  Sure basketball and baseball are played in stadiums and arenas that are different sizes and shapes, but that really does not affect the field of play like it does in baseball.

The quirks found in the ballparks themselves can lead to some interesting occurrences.  For instance the ivy that grows on the outfield walls at Wrigley Field in Chicago, IL will often swallow up a ball so that the outfielder cannot make a play on it.  The flag pole in center field at Minute Maid Park in Houston, TX is actually in fair territory and any ball hit off of it is considered to be still in play (A few years ago this turned a 400+ foot home run by Richie Sexson into a very long single).  Ballparks with roofs also present interesting scenarios as well, like what happens if the ball actually hits the roof?  All these quirks have led to a class of rules know as Ground Rules.  Some ground rules are the same no matter where the game is being played; other rules are specific to that ballpark.  If you are ever at the first game of a series, you will notice that the umpires spend a couple of extra minutes with the manager of the visiting team, making sure that they are aware of the ballpark’s ground rules.

What are the ground rules in architecture?

Often time you think of software architecture as a universal discipline.  We have a set of design patterns that we study and use (sometimes we use them weather we know it or not).  Most software is built on a few platforms (mainframe, midrange, UNIX/Linux, Apple, Windows) and we all rely upon a set of standards that are pretty much Universal (TCP/IP, HTTP, Telnet, etc).  One of the real benefits of this is that from a software architecture perspective we can easily move from organization to organization and our skills can be applied pretty quickly, as long as we learn the ground rules of the industry and organization.

Ground rules in software architecture are anything that is specific to the organization (or the industry), as opposed to universal to our discipline.  One of the first questions I usually ask a customer when I talk to them is about their propensity to build or buy then build.  Does the organization have a mix of desktop and web applications or do they only build web applications?  Do they prefer Java or .NET?  Are there industry standard data formats like ACORD that they must use?  Are their regulations like GLB or HIPAA that they must comply with?

Each of these items has nothing to do with the pure discipline of software architecture, but they are things that will affect the design of any system that you will create.  Not knowing the ground rules can greatly impact the solutions that you create, are can even lead to you being “called out”.  When you start working with a new organization, you should strive to quickly get a feel for the ground rules.

Can ground rules be changed?

Some of the examples I mentioned can be changed.  An organization that purchases packaged based systems could decide to build a solution from scratch (and the converse is true as well).  A Java shop can decide to try .NET on a new application.  Other ground rules cannot be changed, for example a bank cannot decide to ignore GLB.  In general it will be a significant effort to change a ground rule, so approach trying to change a ground rule with caution, and be prepared to invest a lot of time in the change.

Please don’t call it Build versus Buy

In the United States we just finished income tax season.  Like many people I do my  own taxes with the assistance of one of the major tax software packages (the one I actually use is not important).  I purchased the software at a local office super store.  I installed the package off of the CD by clicking a couple of buttons on the wizard.  I updated the software online several times (over the course of several weeks).  I gathered all my data and answered all the questions.  In the end I filed electronically and all was well.  I spent a total of about 5 hours on my taxes and saved several hundred dollars over going to a tax professional.

Buying a single user software system (such as the tax software) is as close to a pure “buy” in the “buy versus build” decision as any of us will ever get when there is custom data involved in the application.  But most companies will spend a lot of time and energy discussing / debating / arguing the question of should they buy or should they build without ever question the fact if they are actually buying a solution or not.

Buy then build is what we usually do

When we buy a package based solution of any complexity it does not usually come “out of the box” ready to use like the tax software that I used to do my income taxes.  There is a lot of work that needs to be done to get the application running in your environment.  I am speaking of activities beyond actually installing the application on the servers and desktops (which can be complicated in and of itself).  Even in something as simple as a General Ledger application included in an accounting package there are literally dozens of decisions that need to be made before the system can be brought online and loaded with your data.  And often times, loading of the data is the hardest part of all. 

We (as an industry) tend to compare the cost of building a solution with the cost of purchasing a package based system.  When we do the math, we usually include a very naive and extremely low estimate of the cost of getting the software up and running.  We tend to underestimate all the configuration, test and integration cost (that usually involves some software development) to get the package integrated into our environment.

Configuration is building

If you have ever been through the due diligence process on a packaged based software evaluation, you will often hear from the vendor something to the effect of “that is a configuration item, not custom code”.  The vendor is telling you that this is a parameterization option in the software.  While you may not have to write code to get it to work, you do have to get the parameters correct and more importantly, you have to test the application with the specific parameters that you have configured and you have to do all that in the presence of your data.  The configuration process is “building” software, even though it is not writing code.  I have actually been involved in packaged based implementations where there have been literally dozens of people on the “configuration team”.  They may not be developers, but these are still resources that you need to acquire (sometimes scarce resources that can cost you more than developers).

Yes I believe in purchasing software

I want to make sure that nobody confuses my stance on package based software.  I think it is a very healthy thing for organizations to buy software packages, especially in areas that the software will not provide them a competitive advantage (easy example: you will almost never get a competitive advantage out of your account process – so that is a good thing to purchase).  As an industry, we need to be a little more honest with our terminology and not call it Buy versus Build, but rather Build versus Buy then Build.

Attention to every detail

On Sunday the family and I went to the Milwaukee Art Museum to see an exhibit (the exhibit was wonderful, but that was the last day, so I won’t tease you with the details).  Milwaukee has a wonderful art museum, but there is one downside to the museum and that is that the building itself can be a huge distraction from the works of art inside the museum.  The building itself is a real work of art.

The art museum itself is actually a couple of buildings, and what most people think of as the museum is actually the Quadracci Pavilion that was built years after art museum was opened, although the building is quite often referred to as “the Calatrava”, after the architect.  The building was designed by Santiago Calatrava a Spanish architect who has built dozens of structures around the world (including such great works as the Turning Torso).  The crowning glory of the building are the “wings” that raise and lower during the day.  But as you wander around the building (both inside and out) you notice there are many great features to the building.  You can easily spend hours in the building amazed at the elegance of the structure (while you are there, do spend time looking at the art that the building contains).  To me one of the most fascinating parts of the building is actually the parking garage.


There are a couple of parking garages that you can use, I am talking about the one that is actually a part of the building itself.  It is an underground structure that is located below the Quadracci Pavilion.  The building is actually on the shore of Lake Michigan, so I am sure it is an engineering marvel because the garage is below ground so close to the lake.  But I am amazed how the parking garage has been incorporated into the structure and the theme of the overall building.


Normally you think of a parking garage as a very utilitarian structure and the design usually reflects that notion (imagine concrete pillars that are evenly spaced through the structure).  The garage at the Milwaukee Art Museum reflects the design of the overall structure.  You can see how the lines of the pillars in the photo above are harmonious with the lines inside the building in the photo photo of my son; the spine type structures run the length of the building on both sides (the shape of the garage pillars are different because they are in the center of the building).  I can honestly say that it is the only parking garage that I have ever been in that I would consider elegant.

Applying the principal to software design

Like the parking garage at the museum, most software applications have components that are utilitarian in nature.  The canonical example is the administrative interface that is only used by the system administrator.  Often times these are “CRUD” interfaces used to maintain reference tables used in other parts of the application.  These interfaces are often slapped together (I have heard more than once phrases like “that is a good job for the summer intern”).  Even if the interface is not used by every member of the application it does not mean that it should not flow with the rest of the application.

Not just user Interfaces

The administrative interfaces are an obvious example, but there are also non-visible portions of the application that some times don’t get the attention that they deserve.  There are always components that are not as “sexy” to build (think of the rating engine for an insurance company), so often times they are neglected.  Often times that are components to the system that don’t fit in with the rest of the application just because they lack some attention to detail (no XML Comments, missing or inadequate unit testing).