Slashdot Mirror
Why Microsoft Developers Need a Style Guide
snydeq writes "What your interface communicates to users can be just as important as what your software does, writes Fatal Exception's Neil McAllister in discussing the latest edition of the 'Microsoft Manual of Style', a style guide aimed at designers and developers who create Microsoft software, as well as those who write about it. 'The gist of much of Microsoft's advice is that a user's relationship with computer software is a unique one, and it's important to craft the language of software UIs accordingly,' McAllister writes. 'Occasionally, Microsoft's recommendations verge on the absurd. For example, you might not think it necessary to admonish developers to "not use slang that may be considered profane or derogatory, such as 'pimp' or 'bitch,'" but apparently it is.'"
You silly open source GIMP developers...
The only intuitive interface is the anus, and even people like goatse mess it up.
Cancel, or "pimp this bitch"
How about, when naming variables, you have to put the first letter of the typename in the start of the variable name!
And then later let's change the types in the API but keep the unmatching old names for compatibility!
AFD.SYS does not mean "Ancillary Function Driver"... but you didn't hear that from me.
Obviously they do have to put in the bit about not using words that some might find offensive in case someone, having a bad day, put it in and they had no come back.
It's quite incredible what some developers, at any size of company, will do sometimes.
'Pimp the Bitch'
Take the 'Malicious Software Removal Tool' for one example. Sounds to me like a malicious program that goes and removes software from your computer. They should have called it the 'Tool for Removing Malicious Software'. I look at such ambiguity with a laugh. I recently had a dialogue box on my computer saying something along the lines of "Problem Reporting _____". (I forget the exact text.) Does that mean that the system is reporting a problem, or having a problem reporting? Considering that most users of the software are not experts, they should try harder to make things less confusing.
I just want to go on record as saying I hate this headline. I didn't pick it. Furthermore, I don't think there's anything in particular about Microsoft developers that makes them "need a style guide" more than anybody else, and that notion had absolutely nothing to do with my column. I just thought it was interesting that a Microsoft style guide exists, that it's available for sale, and that it has some interesting stuff in it about writing for software UIs that a lot of developers probably don't think about. That's about it.
Breakfast served all day!
Similarly, the relationship between USB peripherals could be described as "master/slave," but these terms could also be considered offensive. (The "Microsoft Manual of Style" says such language is prohibited in "at least one U.S. municipality.")
Dear Neil McAllister,
That terminology originally comes from disk drive buses, and the municipality is Los Angeles. Are you really a tech writer?
Sincerely,
Suspicious
Bio questions? Ask me to start a Q&A journal. Computer analogies available for most topics!
Choose the single leg double-hand overarm for distance.
Or, if you want maximum impact, and hence noise when the chair lands, go for height: a full seat grab upper thrust is your best option.
Then there's the full intimidator, often accompanied with shrieks alluding to colorfully burying someone whilst holding it by two legs high above your head - this move requires two full laps of the office before deployment.
Why MS devs need a style guide: they thought the ribbon was a good idea. 'Nuff said.
And - people can not avoid or fix mistakes which they do not know about.
Silence on an issue = consent. So, if MSFT had not mentioned avoiding "'pimp' or 'bitch"; someone raised in an environment where that was ok - (looking at you, teens and young twenty-somethings who grew up saying "That's Gay" when you meant wrong, bad, or odd) may not fully realize the problem with borderline and unacceptable language.
Example: Error Message = "What a bitch! Just dumped a debug file in my program folder" or in the HELP>ABOUT saying "Hey, if you want additional functionality, allow me to pimp the ENHANCED version @ paymemorecash.local"
Once when discussing hard drives and controllers, I asked my co-workers, "It is primary/secondary and off of those master/slave or the other way around? I don't do hardware enough to remember those things."
One of my co-workers was African American and after that came out of my white mouth, I regretted it: not because I'm PC or anything but because I truly respected him and admired his skill as an engineer.
My African American co-worker being an uber-geek-professional and without missing a beat answered it.
I really hate the whole race relations in America.
Say what you will about Obama and his polices, but having a black President has really helped us as a people in the States and I hope it has added to the healing.
'Occasionally, Microsoft's recommendations verge on the absurd. For example, you might not think it necessary to admonish developers to "not use slang that may be considered profane or derogatory, such as 'pimp' or 'bitch,'" but apparently it is.'
Spoken like someone who's never written, read, or worked with any kind of code whatsoever. It's not uncommon for comments to contain language others outside the team will find offensive - developers get comfortable, and start writing for each other instead of the world at large. Since MS releases their code to outside parties, they feel the necessity to remind their coders to remember they're not the only ones reading the source.
Twit.
You may be familiar with design patterns. Those in the know sometimes give them nonstandard names, such as:
...admonish developers to "not use slang that may be considered profane or derogatory, such as 'pimp' or 'bitch,'" but apparently it is.'"
Microsoft does not want their true relationship with their customers to become widely known.
Silence is a state of mime.
Back in the design days of the original macintosh they used Do It instead of OK, apparently a guy got frustrated and in anger asked "I'm not a dolt, why is the software calling me a dolt?"
http://www.folklore.org/StoryView.py?project=Macintosh&story=Do_It.txt&sortOrder=Sort%20by%20Date&detail=medium&search=do%20it
while the derogatory terms etc may seem obvious, there are plenty of less obvious mistakes that people fall into. For instance we used naming conventions on errors in on of our production applications that referred to greek mythology and specifically the underworld. It came as quite a shock when we received official complaints from religious nutcases that said they were offended by our blasphemy. Since then we have had to rewrite a lot of that to use far more boring errors.
"came as quite a shock"
Probably better said than what I wrote. When you are generating something for mass consumption, you have to guard the sensibilities of the most sensitive persons.
Of course, one could go on their own rebellious way, and have a small but loyal cult following - however I believe most of the code written for programs is destined to be seen by more than the general three-close-friends.
Well, if you were writing software for say... a dog tracker & Information application such as for breeding dogs..
You probably would not want to use the wording "Pictures of Studs" and "Pictures of Bitches" as a link to the gallery of the dogs' photos... Even if it's legitimate and correct usage!
It was written for technical writers and editors, not for developers.
https://developer.apple.com/library/IOs/#documentation/UserExperience/Conceptual/MobileHIG/Introduction/Introduction.html ...
https://developer.apple.com/library/mac/#documentation/UserExperience/Conceptual/AppleHIGuidelines/Intro/Intro.html
http://developer.android.com/design/index.html
http://developer.gnome.org/hig-book/
http://docs.blackberry.com/en/developers/deliverables/36511/index.jsp?name=UI+Guidelines+-+BlackBerry+SmartphonesBlackBerry+Smartphones7.1&language=English&userType=21&category=BlackBerry+UI+Guidelines&subCategory=
http://docs.blackberry.com/en/developers/deliverables/27299/index.jsp?name=UI+Guidelines+-+BlackBerry+PlayBook+TabletBlackBerry+PlayBook+Tablet1.0&language=English&userType=21&category=BlackBerry+UI+Guidelines&subCategory=
http://wiki.eclipse.org/User_Interface_Guidelines
Yeah, its hilarious an unusual that Microsoft publishes a design guide for their OS because obviously the author didn't spend 5 minutes on Google...
I haven't thought of anything clever to put here, but then again most of you haven't either.
I couldn't care less about the "style" of coding (aka comments), as long as it works. More importantly, that the code is efficient as possible. Focusing on style before functionality detracts the overall effectiveness of a program, imho.
Why would anyone adopt the "style" that was used to create the Ribbon Interface? Total absurdity!!
Erm, so the argument is that something that is considered poor style shouldn't be mentioned in a style guide? Doesn't hold water I'm afraid.
Whether or not it's obvious isn't even relevant. The point of the style guide is to prescribe good style. It's obvious you shouldn't drive your car on the sidewalk, so why have a law against it?
What's more, the question of how best to refer to the user really is of interest to developers who weren't itching to type 'bitch'. Some likely options:
'Occasionally, Microsoft's recommendations verge on the absurd. For example, you might not think it necessary to admonish developers to "not use slang that may be considered profane or derogatory, such as 'pimp' or 'bitch,'" but apparently it is.'
IT skews dramatically male, and those men skew dramatically towards the socially inept. Making explicit rules about not using profane or derogatory slang in your UI is completely appropriate.
"The urge to fly from modern systems, instead of moving through them to even greater, fairer things is, I think, an indi
That's retarded... You and your Political Correctness police can go to hell.
If you want language guidelines, the proper thing to do is just state that ALL SLANG IS VERBOTTEN in business environments. Problem solved.
The other problem is non-native speakers. You can only do so much to protect them from themselves. Now if you'll excuse me, I've got to go do the needful...
Slashdot gets worse every day... Pipedot: News for nerds, without the corporate slant
I'm doing some .Net code for one of Australia's main agricultural shows and when working on the dog judging reports I regularly write code like GetBitches(int showYear, int sectionID)....
Don't tell Redmond
Nah, MS progs just need a copy of Programming Basics 101, then they might finally make something secure, fast, and that doesnt need 3 gig of ram just to produce a gui. Style guides are for *advanced* programmers, not beginners.
Sadly sometimes you do need to remind people not to use certain terms in their programs or documentation. I recall one fellow submitting material in which he displayed the text "like an acid trip". When I pointed out that might not be an appropriate description to put in he agreed and made the edit. It's a good idea to have these policies on hand just for those moments when people get carried away.
It's not MY political correctness police.
These have become social norms. Norms, that you are FREE to violate. However, violation may come at a cost.
If you are self-employed, you may lose customers.
If you are an employee, you may lose your employment.
I've LOST positions due to language issues/barriers. I'm pretty sure other people have as well.
Much the same way as "http://hothardware.com/News/Tweet-Your-Way-to-Losing-a-Job-Offer/"
Hungarian notation is this ingenious little recommendation for naming your variables to describe the expected contents of that variable when the type won't do. So, if you have a std::string field containing a hex version of a GUID, you might name it guidAsHexChars. Microsoft took Hungarian notation literally to mean naming it after the type. So, you've got a lot of redundantly named variables like guidString.
I swear to God...I swear to God! That is NOT how you treat your human!
1) Software is a conversation. Be polite.
2) Software is a servant, not an equal or a master. Software is the waiter. Don't put behavior in your software that you wouldn't accept in a restaurant.
The most aggravating and common user interface fails to avoid are:
1) Interruptions (e.g. Microsoft dialogs telling you updates have been installed, as if you give a rat's ass, refreshing a window or dialog that doesn't appear to need to be refreshed, being too helpful and hovering like Clippy).
2) Being ignored (Clicking or typing on screen and watching nothing happen).
There are, of course, many other transgressions, but most of them can be addressed by thinking through a restaurant example. If the waiter came and rearranged your dishes and silverware in the middle of your meal, you'd be furious. If the OS comes in and rearranges your screen while you're working, taking away your focus, you'll be furious. If the waiter keeps ignoring you or is slow, you get angry. If the OS keeps ignoring you, or gets slow, you get angry.
There are thousands of things you can do to improve an interface, but miss this stuff and you fail.
Please do not read this sig. Thank you.
Hey, that's me! I kicked the habit cold-turkey when a gay coworker hired on. I still occasionally have trouble with "retarded", and South Park certainly doesn't make it easier.
And sometimes not-mistakes. As some of the executives of a company I once worked for had to explain away (to a female user working for a major customer, naturally) an error box written by an ex-employee by claiming it was simply an unfortunate typo for "count error".
Since then we have had to rewrite a lot of that to use far more boring errors.
Why didn't you rewrite the code to not produce the errors in the first place?
Reminds me of a story from way way way back. Supposedly, part of the copy-protection scheme for Lotus 1-2-3 for DOS contained an invisible file named SATAN.666. Again, an invisible file that no one would ever see.
When PC Week or some other magazine mentioned this in an article, various churches who used the product were quite upset. I believe Lotus sent the complainers new versions of the software with the file removed.
I know, personally, I had one of those dialog boxes that a user should never see which had a "Shit" button. The only user that I ever heard of seeing it, unfortunately, was Jean Louis Gassee when we were doing a demo at Apple.
ahhhh I see, so rather than show an error when the WAN link has become unavailable or the remote link to an external organisation that we don't control isn't working or even when a server has failed we should rewrite the code to just... do nothing?
They already have one, but it doesn't really go beyond them trying to cram that ribbon bar into everything.
I've seen similar things on a FOSS development mailing list. People who program computers by defining algorithms try to program people by doing the same thing. The result is:
1. Millions of crazy rules that are obvious.
2. Nobody can keep track of the rules and as a result they get broken a lot leading to flames.
3. Tons of effort gets diverted towards rule-maintenance and enforcing relatively unimportant rules.
4. When somebody does something dumb people flock to their defense if it didn't violate the rules.
The same problem creeps into organizations that are run by lawyers - the legal system is like one big computer that tries to churn through rules.
Small innovative companies survive by having strong founders who aren't afraid to ignore the rules. If somebody working for them messes up they get called for it or booted - and since they probably don't have deep pockets yet they can often get away with it.
So, if you wonder why MS has a rule about not using 4-letter-words in UI elements, chances are some idiot stuck one in, and then when their boss tried to ream them out for it they quoted the rulebook and pointed out that they didn't violate anything. So, now we have a rule.
No matter how much you idiot-proof a system, somebody will design a better idiot...
You never know what may offend someone. It's unpredictable. Like Arthur Dent who accidentally caused an intergalactic war with the words "I wouldn't want to go anywhere without my wonderful towel".
I work with a team of .Net developers who seem to spend all of their time arguing about naming conventions, what namespace to use, whether something is a noun or a verb, etc. I'm not a "software engineer," but I have written my share of software without this ever being the majority of my time. I think this problem may be more common with people who are writing code for the sake of writing code rather than making software that solves a user's problem. I think it's a defense mechanism so they can avoid admitting that they don't understand what they've been asked to do. If my suspicion is accurate, these guys are doing the profession a disservice and should consider a new line of work.
Clippy: "It looks like you're trying to pimp your presentation. Would you like some help with this?"
Options: "Yes. Show me how to pimp my document!"
"No, fuck off you annoying little shit!"
"If I have to turn you off in the options again I'm gonna bitchslap my laptop!"
Operation Guillotine is in effect.
Indeed, I did not expect "pimp" or "bitch" from Microsoft developers. I guess they're getting the best and the brightest, these days. #sarcasm On the other hand, Windows 7 is pretty boring and it feels like I paid an awful lot for an OS that is no better than Windows 2000. If only it came with some entertainment... a "pimp" or "bitch" button would really help me feel connected to my computer.
So "(Pimp)this.reachBack().slap(this.theHoe);" is not an appropriate statement?
An homage to "Boyz in the Hood." See the Dynamite Hack interpretation of the original. ;-)
What you say is true but irrelevant. IDE is largely obsolete so USB is an example more familiar to the target audience. In addition, the precise details of the incident are outside the scope of the document - which, may I remind you, is about UI guidelines and not the history of technology and its influence on the civil rights movement. It was mentioned just to illustrate a principle.
Got the painters in, have you?
Confucius say, "Find worm in apple - bad. Find half a worm - worse."
I guess my ebonics version of clippy is out then:
"Hey bro, youse seems to be trying to slap some bitchin' screed"
2) Software is a servant, not an equal or a master.
Can we talk about this, Dave?
Step 1: Offer a new software function.
Step 2: Wait for two new generations of the software to be released, and the function mainstreamed.
Step 3: Remove the function.
Step 4: See how many bitch.
Step 5: Don't reinistate the function. The little geeks will just work up a kludge on their own.
When the going gets weird, the weird turn pro. ~~ Hunter S. Thompson
Software development is a form of art where Math/Logic/Science/Engineering are our mediums to work with. Being an art form the software developer feels the need to express themselves in their program, in one way or an other.
However much like real artists in order to make a living they need to do a buch of commissioned work where you need to make what the boss wants and your personal style is limited. And as you get more artists on a project you need a style guide to make sure the project is consistent.
GNU projects often lose a good UI compared to their closed source counterpart because each artist is making their own statement in the program. I find that the GIMP does this. Now this isn't a flaw in the GNU but a good GNU project needs the same oversite and rules a good closed source solution needs, and often much earlier in the process because open source you get a lot of people doing a little bit of code, while closed source you get a few people doing the bulk.
If something is so important that you feel the need to post it on the internet... It probably isn't that important.
There are even more subtle examples. I'm not sure if it's still there, but one of the examples from the old Mac HIGs was the owl. In most European cultures, it is associated with wisdom, so it makes a good icon for a help system. This, however, is not universal and in some places owls are associated with the occult and with evil. People in these locales generally won't expect to click on an owl when they want help, unless it's to curse the idiot who designed the UI that is confusing them.
I am TheRaven on Soylent News
I remember being infuriated by this message, it's meaningless and too casual. It doesn't provide any information as to the cause of the error nor does say "unkown error". It makes me wonder whom is it embarassing for. Me? Mozilla? Firefox itself? Does it mean "we're sorry for you using such crappy software"?
I wonder about how this message is perceived in company/corporate settings. It's an exemple of bad writing style to me. You've crashed, don't try to be familiar or funny about it.
That's the way everything seems to behave on windows.
Rethinking email
Just found out today that you have to enable javascript to be able to see your account settings. In the past, this worked perfectly to change the threshold of posts if you have mod points.
Now, either a programmer or web designer, or both, was allowed to futz with the design of a web site when they had no reason to do so, a violation of Rules 1 and 2 of IT That Should Never Be Broken.
The continuing downgrading of functionality of this site is getting bad. Simplicity is the key. There was no reason to add bells and whistles. There was no reason to make things more inconvenient for the user.
This is why programmers and web designers should never be allowed to design applications or web sites. They should be told what to do and not left to their own thoughts as to how things should be done.
We will bankrupt ourselves in the vain search for absolute security. -- Dwight D. Eisenhower
Microsoft style will show you the 'Windows is rebooting to install updates" screen instead ?
You never know what may offend someone. It's unpredictable. Like Arthur Dent who accidentally caused an intergalactic war with the words "I wouldn't want to go anywhere without my wonderful towel".
No no no no no!
If you are going to quote Arthur Dent and HHGTTG on /. you need to get it right.
"I seem to be having tremendous difficulty with my lifestyle." is the correct quote that started an intergalactic war.
Sheesh!
Yeah. What Microsoft needs to do first is to STOP making absurdly complex, undocumentable Rube Goldberg machines like WPF and XAML.
Then we can talk about a "style guide".
Where are the mod points when you really need them?
Singularity: a belief in the "God" idea with the "demiurge" relation inverted.
Having once used "asss" as some dummy text in a project for a multinational client ( it randomly fit well into the copy and was mistakenly presented to the VP ) - I can tell you it causes a lot of headaches for the people who aren't developers and have to explain it.
The "silly" parts of style guides (having worked with them many times) tend to be those written by the legal departments. They're silly because big companies are targets and they have to be careful of what they do. I think everyone on this site thinks copyright laws often are silly when it comes to technology and Microsoft is a big target.
The rest of the points are just like any style guide: in coding/development they're called "best practices" or "design patterns" and it's not a bad thing. Read Knuth again - 1/4 of it is a style guide.
That's not unfortunate, you're j-j-j-just h-h-h-handi-capable... very much