According to Readers Digest, there's a dyslexic agnostic insomniac out there somewhere who lies awake all night pondering on the meaning of dog. Thing is, it really should be "doG", not "dog". But it seems that, according to our most recent style guide here at Microsoft, capital letters are fast becoming obsolete, although it's probably not so that jokes like this will be more accurate.
The aims of the style guide updates are constructive and practical. We should provide help and guidance only where it will be useful, and phrase it in such a way that it appears friendly, open, and easy to assimilate. All very sensible aims, though I've yet to discover where simplifying content so that it makes it harder to use, or sprinkling it with exclamation marks and apostrophe-shortened words (such as "don't" and "shouldn't") is advantageous.
But behind all this is an undercurrent of practical mechanisms for actual word styles and structure. For example, in the previous paragraph I committed the sin of "excess-hyphenation" (or, to be more exact "excess hyphenation"). I'm sure Microsoft style gurus aren't aiming to purge documentation of all hyphens, though it sometimes feels like it. I now have to use "bidirectional" instead of "bi-directional", "rerouting" instead of "re-routing", and "cloud hosted" instead of "cloud-hosted". Though it seems I can still get away with "on-premises", as in "deployed to an on-premises server". Perhaps "onpremises" is just one step too far. Though I do like that they ban the use of "on-premise" because a premise is, of course, a proposition upon which an argument is based or from which a conclusion is drawn.
And then there's the race to remove capital letters from as much of the content as possible. Things that used to be a "Thing", such as "Windows Azure Storage" are now just a "thing", such as "Windows Azure storage". Tables are now tables, and Queues are now queues. I did think that "BLOB" might survive the cull because it's an acronym for Binary Large Object, but sadly no. It's now a "blob" in the same way as a patch of spilled custard is.
Mind you, there are other rules that make it hard to create guidance that reads well. I still haven't found a solution for the repetitiveness in phrases such as "stored in an Active Directory directory", or the fact that the Access Control Service (ACS) is no longer a service; it's just "Access Control" and can't even have "service" after it. So "authenticated by ACS" now becomes "authenticated by AC", which seems too vague so I end up with "authenticated by Windows Azure Access Control" and repetitive strain injury.
I get that over-capitalization and excess hyphenation can make the text harder to read and assimilate, and that we need to provide friendly guidance that uses familiar words and styles. And thankfully I have wonderful editors who apply all the rules to my randomly capitalized and hyphenated text (though, sadly, not to my blog posts). But I wonder if we'll soon need to start writing our guidance in txt speak. imho well mayb need to 4go sum rules b4 its 2 l8...
I wish the Visual Studio designers had consulted this style guide before designing the MENUS in VS2012 ;)
Yep, I was waiting for this to come up! Thanks Brian - if I was giving prizes you would have won. We're having an editorial discussion at the moment about how we present this in our documentation. In the meantime, did you see this post: www.richard-banks.org/.../how-to-prevent-visual-studio-2012-all.html