I’m often asked for best practices by folks looking at new technology. Best practices should be something that, having been tested multiple times in many scenarios, provide the most likelihood of good performance. In reality, they tend to be highly conservative, “works for me” designs that may provide a starting point but probably not much more.

But, you say, everyone else is using this best practice document published on the Internet by some authoritative sounding group, so Matt must be wrong again!

Well, when we were kids, we were told not to do something just because everyone else is doing it (unless you count this particularly insightful take by Randall).

The desire for a best practice document is to shortcut a painful learning experience with a configuration that works. We know that the best practices probably aren’t best, but at least there’s a document that tells me what to do. Some IT managers may not understand that concept, expecting the best practices are just that, best. Without getting into a rant, ITIL is a framework and a guideline, not a proscribed daily regimen. Every environment could do with a little tweaking for optimal performance. But sometimes good enough is perfect.

What we want aren’t really best practices. What we want are workable reference architectures that can be easily modified and better guides on how to install systems and applications. Reference architectures usually aren’t part of the standard packaged documentation delivered with software. If they exist, they are written by a separate group at a vendor, or perhaps a reseller, and may not tie back well to the standard docs. And sometimes, they aren’t well written at all.

There’s a fundamental problem in software documentation, how do you present all the relevant materials while including all of the potential scenarios? We’ve all experienced installation guides that give us no actual workflow for installing the product. We started on one path, followed a tangent to another end, came back around to a third point before delving into some other special case. Then we move on to the next button, option or widget. At the end, we still have to cobble together the right sections to build the workflow, hoping we understood the key concepts.

Guides: Evaluation vs. Installation

One of the better sets of documentation I’ve read recently came from Red Hat around their virtualization platform. Some smart folks decided that they needed to put together a guide that would assist customers in getting the tools running and start using them right away. This evaluation guide is probably one of the best quick start guides I’ve seen. How is this different from the installation guide?

Mainly, the evaluation guide sets out a workflow and only deals with those steps. The installation guide discusses all of the possible options at each step. The installation guide does have a workflow laid down at the beginning and signposts at various points of the documentation, but even if you jump to a workflow section on installing the manager, we still get upgrade and uninstall details. The evaluation guide’s only purpose is to get a working RHEV environment running so you can start test cases.

Now the evaluation guide is not the “be all, end all” of RHEV deployments. It’s a workable but not necessarily high performance configuration. Here we need to add a reference architecture that explores specifics of performance characteristics and hardware specifications. Again referring to Red Hat’s Customer Portal, the Reference Architectures contain network diagrams, driver install guidelines, firewall rules, package additions, etc. Combining the workflow specific framework of the evaluation guide with the detailed architecture of the Reference Architectures can get you to the desired state of “best practices”.

As we start looking at cloud environments, these sorts of cries for “tell me where to start” get louder. Many of our old lessons don’t apply in this brave new world of abstracted resources and multiple availability zones. There’s a new architecture paradigm to embrace and new rules of the road. Amazon has started an “Architecture Center” to provide some overviews of how to use their tools. But even here, reference architectures and workflow based guides provide the same jumpstart as they do in traditional data center environments. Best practices are going to provide the best of the mediocre. Demand more. Learn better.

Or is there something really wrong with the bridge?