Convention over Documentation

Convention over Configuration seems to be an increasingly popular approach to software development, especially in a world of increasing development frameworks. I think the general principle holds a lot of promise for the world of IT as well.

What is Convention over Configuration?

I think the best place to start is to summarize the idea of Convention over Configuration -- and I think the best way to explain it is by an over-simplified example:

Imagine you have a framework that automatically took objects you've created in your code and saved them to database. A traditional approach would be to have some kind of configuration file that contains maps which classes go into which database table. Something like:
<class table="&biz_users"& name="&BusinessUser">

Using the principle of Convention over Configuration, the designer of the framework might simplify this and simply specify that all classes will be saved into database tables with the same name as the classes. While it may take a little bit of re-work to make sure class names will all make valid database table names, you are accomplishing several things:

1. You're removing a layer of complexity without significantly affecting your flexibility. You can still have tables named whatever you want, your code just has to match.
2. You're eliminating a whole series of bugs that could arise from type-o's or other errors in your configuration file.
3. You're making troubleshooting a lot easier, because you can look at the database and know exactly what class each table is representing without having to go back through an additional configuration file.

In short, you're saving yourself a lot of work and potential headaches.

How does this apply to IT?

I think the ideas behind this software development principle could more adequately applied to the IT field as "Convention over Documentation".

For IT shops managing multiple clients, often each client has their own set of documentation for how users are setup, how drives are mapped, how printers are installed, etc.

The principle of "Convention over Documentation" would say to come up with a standard set of "conventions" that your IT shop uses, then reconfigure clients to match these conventions and document any exceptions.

An Example

I think it's easiest to explain this with an example contrasting "Convention over Documentation" with a more traditional "Documentation-only" approach:

You may have some clients that have network printers directly installed on their PCs, other clients may have printers shared off the server and manually setup for each user, and others may have different kinds of scripts mapping network printers.

If you leave clients all configured differently, any support requests for network printer installations will involve:

1. Support technician looking up printer install documentation on this client
2. Support technician going through documented install process for this client (or more often, support technician going through whatever install process they are most comfortable with)
3. Support technician updating documentation on where printers are installed

And that's not even considering what to do if this is a request for installing a new printer, or the support technician needs to troubleshoot a problem with printing. If you have real-world IT experience, you've probably seen what kind of mess this process often produces.

Using the principle of "Convention over Documentation", the IT shop would have a standard procedure for installing network printers (hopefully one that enables centralized management). The process for setting up a printer for a new user would be more like this:

1. Support technician connects in to client's print serve and identifies the printer needed.
2. Support technician modifies user's Active Directory account so that group membership will trigger scripts to install this printer for the end user.

Hopefully, this will cover most cases, but like anything with IT, there will inevitably some client that needs printers installed differently from your established standard. I would argue that having a standard convention makes identifying exceptions more straight-forward:

While going through the installation process, if the printer isn't installed on the print server, or the appropriate Active Directory groups aren't created, this will trigger the support technician to go look for a documented exception to the standard configuration.

Arguments *for* "Convention over Documentation"

1. Reduces the amount of documentation, and therefore decreases the potential for inaccurate, out-of-date, or incomplete documentation.
2. Increases the speed at which support incidents can be addressed by: (1) reducing the amount of time the support technician spends reading documentation and (2) increasing the familiarity of the support technician with the client's configuration.
3. Reduces configuration mistakes since each configuration is basically the same.

Arguments *against* "Convention over Documentation"

1. The approach requires reconfiguring client's networks, which takes time
2. There will inevitably be some good reasons some clients may have for their network being inconsistent with an IT shop's established standards.

Personally, I think that, in most cases, the amount of time you save in the future and the other effeciencies gained by consistent configuration more than makes up for objection #1.

As far as #2, while you will inevitably have some exceptions, I think some simple guidelines will help with handling them effectively:

1. Make absolutely sure that an exception is required.
2. Make sure your standard process helps the support technician identify exceptions.
3. Keep all exceptions documented and keep the documentation easily accessible.