An Upper Case of Indecisive Instruction

A couple of weeks ago I was ruminating on how somebody in our style guidance team here at Microsoft got a new Swiss army knife as a holiday-time gift, and instead of a tool for removing stones from horse's hooves it has one for removing capital letters and hyphens from documentation. Meanwhile the people in the development teams obviously got handkerchiefs or a pair of slippers instead because they are still furiously delivering capital letters whenever they get the chance.

As you will probably have noticed, the modern UI style for new products uses all small capital letters in top level navigation bars and menus. I guess your view of this is based on personal preference combined with familiarity with the old fashioned initial-capital style; I've seen a plethora of comments and they seem to be fairly balanced between like and dislike. Personally I quite like the new style, especially in interfaces such as the new Windows Azure Preview Management Portal. It looks clean and smart, and fits in really well.

Meanwhile my editor and I have been pondering on how we cope with this in our documentation. No doubt some official style guidance will soon surface to resolve our predicament, but in the meantime I've been experimenting with possibilities for our Hands-on Labs. I started out with the obvious approach that matches the way we currently document steps that refer to UI elements (bearing in mind the accessibility guidelines described in It Feels Like I've Been Snookered).

For example:

    Choose +NEW, select CLOUD SERVICE, and then choose QUICK CREATE.

But written down on virtual paper that does look a bit awkward and "shouty". Perhaps I should just continue to use the initial capitalized form:

    Choose New, select Cloud Service, and then choose Quick create.

However, that doesn't match the UI and one of the rules is that the text should reflect what the UI looks like to make it intuitive and easy for users. Maybe I can just use ordinary words instead, in a kind of chatty informal way, so that they don't actually need to match the UI:

    Choose new, select cloud service, and then choose quick create.

But that looks wrong and may even be confusing. Perhaps I should just abandon any attempt to specify the actual options:

    Create a new cloud service without a using custom template.

Though that just seems vague and unhelpful. Of course, you might assume that a user would already know how to create a new cloud service, so it's redundant anyway. But something more complicated may not be so obvious without more specific guidance about where to start from:

    Open the management window for your Windows Azure SQL Database.

I did suggest to my editor that we simply run with something like:

    Choose the part of the window that contains what appears to be some
    text that would say "cloud services" if it was all lowercase, and then...

Ahh, but wait! In a non-web-based application UI I can use shortcut keys, like this:

    Press Alt-F, then N, then press P.

Oh dear, that violates the accessibility rules, and doesn't work in a web page anyway. Maybe I'll just go with:

    Get the person sitting next to you to show you how to create a new cloud service.

And, as a bonus, this approach may even foster team cohesiveness and encourage agile paired programming. Though you probably can't call it guidance...

Comments (2)
  1. Daniel Smith says:

    Does Microsoft have some sort of filter that's preventing staff from seeing the mountains of feedback on the all-caps topic?  Even if only a fraction of the feedback is getting through to you guys, there's no way the all-caps issue is "fairly balanced between like and dislike".

    It's currently voted the number 7 most important issue across the entire Visual Studio product!  See here:…/2837384-change-all-caps-menu-in-vs-rc-to-vs-beta-format-fi

    Most issues get a few hundred votes if they're really popular.  This one has literally thousands.

    It's crazy in every conceivable way, including the problems it causes with documentation as you rightly point out.

    People are just lost for words at the craziness of it all :-/

  2. Alex Homer says:

    Hi Daniel, thanks for the feedback. Yes I'm aware of the comments around VS (see my previous blog posts) and obviously I can't speak on behalf of the development teams. However, in many places I think the new style is really attractive. For example, most people I talk to prefer the new Windows Azure web portal that uses this style over the old one. Though I do still need to figure out how to document it…

Comments are closed.

Skip to main content