Vendor Installs

I was recently asked by one of my virtual colleagues if I could review a document they were putting together for an installation of a product that was running an MS SQL back end. After they asked I responded by asking “when do you need this?” They said a week. I said “that’s fine” and did it three days later. True story.

Anyway, it made me realize that other vendors could use some help with their documentation as well. I know, because I see directions from vendors all the time and most of the time they appear to be written by someone with little to no practical database experience. Or writing experience. Or both. In fact, it is almost as if the instructions are treated like they are a burden to put together and the person doing it loathes it so much that the end result is something awful.

With that, I would like to offer some very basic advice to vendors that most every DBA would appreciate.

Tell People Why You Need Specific Permissions

Look, it’s nice that you go out of your way to tell us that your application needs a service account that is a member of the system administrators fixed server role. But what would be nicer is if you told us why you need those permissions. I have seen a wide range of excuses, everything from “we need to create objects in the database” to “it just seems to work better that way”. It is rare that I get accurate details on why such permissions are necessary and to be honest it makes me nervous when a vendor has no idea what their application is doing.

It is okay to tell us why you feel you need these permissions. Honestly. Think of it as a negotiation, if you will. You ask for sysadmin, we tell you db_owner, and from there we can engage in a meaningful dialogue. By the way, if you come to the table and say that you want sysadmin so that way the objects in the database are created as ‘dbo’, then you should realize that we are going to have very little faith in almost every facet of your product. So, it would be in your best interest to have someone provide you with this feedback and you get your instructions updated. That way your future clients will not think as little of you as your current clients.

Use Scripts, Not GUI Interaction

I seem to run across this way too often. The instructions tell me to open SSMS, expand the database, navigate to a table, right-click, and update a row. When I read it, I cringe. Why? Well, two reasons. First of all, there is a LOT of margin for error there. Anytime you have that many touchpoints, you have a chance of error. Second, because an UPDATE statement could have been put into the instructions, it would have taken fewer lines in the documentation, and it leaves far less room for error.

You can put all the pictures you want in your instruction. But if you take three pages to describe something that is essentially a three line update, you are making things far too complex.

Scripts have less room for error, period. Stay away for GUI-based instructions and use scripts whenever possible. If you are doing something such that a script might seem rather complex, then include the script in a seperate file and use some well positioned screenshots to help explain what the script will be doing.

Do Not Mix Terminologies

This happens a lot, especially with regards to logins. A SQL login is not the same as a windows login. AT least, not to a DBA. If you are putting together instructions and have bounced back and forth between terminologies make certain that your point is still clear. Which is my way of saying have someone proofread your work. While logins are a common source of confusion, so is the term ‘reboot’. To most admins, that would be something you do to the entire server. To others they are simply talking about a restart of the SQL services. So why not use the term ‘restart’? Probably because to some people that might mean to bounce the whole box, so they just use reboot anyway because they figure that just makes things easier.

Well, it doesn’t. Especially if you are talking about a shared production server. If your application needs the instance to be cycled, or the server to be bounced, make certain you know which one is truly needed. It is harder to find a window to bounce the whole server, but it can be easier to get the database instance cycled. So, make sure your terminology is very clear, and be careful not to mix them between sections. Whatever you call a ‘reboot’ on page one had better have the same definition on page 27.

And please, stop using SQL logins. If you don’t then I am going to start sending the auditors after you because I am tired of trying to make excuses on your behalf. And if you do use windows authentication, then your install shouldn’t prompt me for a SQL login credentials halfway through, right [product name removed for fear of pissing everyone off again].

Be Clear in What You Are Doing, and Why

If you are going to do anything during your install that affects the server instance (i.e., outside of the scope of your database), then disclose that information. You may think that you are doing someone a huge favor by including a dozen SQL Agent jobs that do all sorts of database maintenance tasks but I have got some news for you: we already have a DBA on staff here, thanks anyway. Loading a bunch of jobs into SQL Agent to do your backups does not necessarily help those shops that already have jobs configured for this. Especially if you decide to do your dumps to a default backup location that is not where the actual backup location exists.

If you feel that you need to include these jobs, then include those details in your install instructions. That way we can easily see what your install will be doing and we can ask questions easily and quickly. Questions such as “I’ll be disabling your jobs right after they are created, did you need some extra sugar for your coffee?” Again, it will allow for a meaningful dialogue right from the very beginning, rather than not learning about all these little things until we are days away from a production deployment.

Look, no document is going to be perfect and serve to give all the right information to everyone. But I have seen far too many examples of poorly written documents, many of which could have been quite good with just a few minor enhancements as noted above. I am willing to wager than if most vendors set aside an extra two hours for documentation review they could produce higher quality information that many DBA’s would be happy to receive. And since we usually end up blogging about your products, you may want to start thinking about some of the things you would like to read about yourself.