Ziggurats, Batman and the Town Crier

We asked Brian for a description of the Help System for the software he's working on and ends up quoting Blake's poetry, discussing town criers, Ziggurats, security guards and the BRAD signal.

A technical author writes about delivering user assistance in SQL Response

SQL Response is a SQL Server monitoring tool developed by Red Gate, planned to release at the end of September 2008. It’s aimed at any DBA wanting to ensure the general health and well-being of the Servers for which he or she is responsible. We reckon that’s pretty much every DBA on the planet.

The Accidental DBA

We spent a long time looking into what makes a great SQL Server monitoring tool. One challenge that kept emerging when researching SQL Response is that DBAs are all different, and they all want different things. They work in diverse environments, with various sizes and configurations of Server, and so they experience different problems, and therefore have different priorities. They also, rather crucially, have widely varying levels of experience. When we demonstrated our beta version of SQL Response the feedback was positive but interesting; they all liked the tool we’d made, but the bits they liked – and the bits they didn’t – were mostly, well… you guessed it, different.

At this point I must make a confession. I’m a technical author. My role on the SQL Response team is that I’m responsible for every word that goes anywhere near the application (that isn’t code). The words on screen (the static text in dialogs, the names of buttons and options, the tooltips, the embedded popups) are all mine, as well as all the online help that we deliver for the more F1-inclined amongst our users. Yes, it’s true, it is actually someone’s job to write all that stuff. It’s my responsibility, working alongside our marvellous usability expert Dom, to make SQL Response as easy to use and understand as possible, without sacrificing any of its rich depth of features.

The first question I ask as a technical author is the same as everyone else on the team. Who is going to be using this tool? Who is it for? And, even more crucially for SQL Response, what do and don’t they know already about SQL Server?

Ã¼ber-DBA and the inexperienced DBA

We didn’t want a tool that was too complex for the less experienced DBA, but we also didn’t want something that was too basic or simplistic for the Ã¼ber-DBAs, the pantheon of experts who sit atop Mount SQL, dispensing scripts and wisdom to eager acolytes across cyberspace. SQL Response aims to be as suitable for “accidental” DBAs, “DBAs by default”, “developer DBAs” as for experienced, full-time DBAs. SQL Response therefore needs to work well for monitoring a handful of fairly quiet SQL Servers and for intensive, time-critical environments, where gigabytes of data fizz constantly back and forth across the world. We spoke to each kind of DBA when we did our research, and the final product looks to meet the requirements of both ends of the spectrum. In fact, our project pin-board has two photos on it to represent both ends of the spectrum, from the ‘accidental’ or ‘novice’ DBA through to the full-time production DBA. One moody, black and white photo shows a guy in shades, looking pretty cool. The other shows a chap in a blue shirt with a beaming smile. See if you can guess which photo represents each end of the spectrum for us.

full-time production DBAs

From my point of view as the author, the audience positioning of our tool can be a particularly thorny problem. SQL Response is basically an information service. It doesn’t do anything to your SQL Servers (we think this is a good thing in a monitoring tool) but rather, it tells you when things have broken, fallen over, slowed down and seized up. When something bad happens, SQL Response raises an alert that provides you with plenty of useful data so you can diagnose and resolve the problem quickly. It’s like the diligent security guard who patrols the building while you sleep, checking the windows and doors and generally looking out for trouble – small fires in the lobby or ne’er-do-wells with SWAG bags and crowbars loitering by the fire escape. SQL Response never sleeps, it is an ever-vigilant sentinel – but it doesn’t constantly tell you about things you’ve told it to ignore, like a Test Server job overrun for example, and nor does it constantly tell you when everything’s just dandy. It isn’t a town crier.1

Town Crier vs Security Guard

1The metaphor of town crier vs security guard is particularly apt for SQL Response. We surveyed a number of other tools on the market, to compare their functionality with the features we intended to put in to SQL Response. It was amazing how many tools were hung up on big green dials that indicated that a Server was basically healthy, and Star Trek style control panels that showed minute by minute updates of various aspects of performance. I imagine a town crier ringing his bell every hour – “oyez, oyez, 4am and all is well”. The sleeping mayor, merchant, or minstrel in that town isn’t going to be too happy being woken up hourly to be told that nothing is happening!

It’s the equivalent of a security guard telephoning you every hour to tell you that the office is fine. Wouldn’t you rather that he only contacted you when something untoward had happened? That was our starting point for SQL Response. And in case you’re wondering what defines the “something untoward”, that’s entirely up to you. You can configure SQL Response so it only alerts you to the problems you care about. Sweet dreams, DBAs everywhere.

To create a tool that tells you where things are going wrong, we need to be sure we’re giving you the right information, and explaining it clearly enough, so that even an inexperienced DBA can use it effectively. Each type of alert in SQL Response has been reviewed so that it’s presented in as understandable a format as possible, using language that isn’t arcane, in terms that most users would understand. That’s the ethos we’ve applied to the whole product… but then, I would say that. I’m the author. The real test will be when users get their hands on the Release Candidate and send us feedback.

Recommendations

One area of the application that demonstrates this problem and the philosophy for our approach more than any other is Recommendations. As well as alerting you on issues such as Servers going offline, deadlocks, job failures, disks running low on space and so on, SQL Response also examines all the databases on your monitored SQL Servers, and advises you on best practices for a variety of issues.

For example, if you add a SQL Server to SQL Response to monitor, SQL Response may, after a few seconds of poking the machine for info, raise a number of recommendations that you haven’t backed up several databases on that Server. These aren’t alerts, because nothing has gone wrong yet as such; they’re simply suggestions for tasks you may want to perform to optimize your Servers. It’s like a note on your fridge door saying you’re going to need to buy some more milk soon. We’ve separated out alerts and recommendations in the interface, because they are different kinds of information, and because they behave in a subtly different way. So you can, if you’re busy fire-fighting performance issues elsewhere, ignore the recommendations quite happily, and consider them as a to-do list for a less frantic day. If DBAs ever have days that aren’t frantic, that is.

When you click on a recommendation in SQL Response, what you get is essentially just a small chunk of text describing the status of a database that may need some TLC. Each of the eight types of recommendation required someone to write the text explaining what it is we’re advising you to do to your database, and why.

This is not a job that can be left to developers, with their refreshingly anarchic approach to the rules of grammar and spelling. But the problems I faced as the technical author were as follows:

I’m not a DBA, and therefore how can I be sure that what I write is technically accurate? Once it’s in the application, it’s there, forever – or at least, until the next point release.
Even if the info is accurate, how do we cater for less experienced users, who may need more comprehensive assistance (maybe even example scripts to run) to resolve the problem?
Similarly, how can we avoid hacking off the expert DBA with assistance that they don’t need because it’s too basic?

Send for Brad- Creating the Hierarchy of Help

At this point, dear reader, I want you to imagine something akin to the bat signal being projected from the roof of Red Gate towers onto the dark clouds of our English night skies. But not the bat signal, the BRAD signal.

Send for Brad McGehee. Who better to guide us with some helpful information about exactly what our recommendations should be telling DBAs. After negotiating with his agent, I sent Brad some notes about the text I wanted him to look at, and he found himself the latest development build of SQL Response, and within 24 hours, duly delivered several detailed pages of review comments. A speed of response worthy of the Dark Knight himself.

Problem one solved. I was confident about the text in SQL Response. That still left me with problems two and three. I needed to organise the information in such a way that novices and experts could all benefit from recommendations, without feeling either spammed or left in the dark.

The strategy I devised was to limit the amount of recommendation information displayed within the application, but include a link to a web page on our Support Center as part of the chunk of help for each recommendation.

The Support web page contains the majority of Brad’s text, conceptual background explanations of the issue raised by SQL Response and more detailed information about how to resolve it – dealing with fragmented indexes, transaction log backups, page verification, data file sizes and so on. Experienced DBAs, who can be heard muttering about grandmothers and eggs at this point, don’t need to follow the link, and aren’t going to be irritated by the basic few lines they get in the app. Novice DBAs, however, can use the link to read up on the situation SQL Response has identified on their Server, and find help that’s been thoroughly vetted by Red Gate, and particularly Brad.

In a sense, there’s a hierarchy of help that attempts to address the problem of DBAs’ broad spectrum of experience and understanding. Atop the ziggurat of assistance is a basic explanation of the issue within SQL Response; step down and there’s more explanation in our Support Center, step down again, and there’s a range of websites to start you at the beginning.

SQL Response has proved an interesting challenge for a technical author. From clarifying the terminology of all aspects of the application at the start of the project, to naming every button and tooltip, and finally to delivering different layers of help for our profile users, it’s been a very demanding project. Naming the various elements of the application is always a fascinating area, and possibly material for another blog. It always puts me in a mind of a few lines from William Blake’s poem, Infant Joy (written 1789):

I have no name;
I am but two days old.’
What shall I call thee

Blake was known for his prophetic abilities, but it’s amazing that he could predict the issues faced by a technical author when faced with a brand new application in 2008.

On that cultured note, I shall take my leave for now. If you would like to see how this work has all panned out in SQL Response, sign up for the Release Candidate by sending your name and email address to the SQL Response RC team. We’ll then email you more information about where you can get your hands on this exciting release and other news about SQL Response over the coming weeks.