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...
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!
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.
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"
'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.
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
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.
You clearly have never had to work in a programming team environment, when you have to take some piece of shit code written by some half-arse educated script monkey, and actually make it work.....
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".
Don't get pissed with me because you don't completely understand code that someone else writes. Like I said, for me, functionality comes first, and documentation comes second. And yes, I have worked in a team environment. My biggest pet peeve is inefficient code. Really, it's not that difficult of a concept to understand.
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.
"Focusing on style before functionality detracts the overall effectiveness of a program."
"Let's just say, I would never hire you. Functionality should be completely mapped out before you even sit down to code."
So you're saying that you wouldn't hire me based on the "counterargument" that functionality should indeed come first, which is what I said to begin with. Reasoning like that only comes from someone who happens to be a complete retard. You speak briefly of management and years of experience, yet fail to even begin your post in a cohesive, non-contradictory manner. That alone invalidates whatever point(s) you're trying to make. As such, I would either find a different company to work for, or I would go about finding a way to replace you before your apparent incompetence ruins the actual development process.
My point is, functionality comes first. If the code doesn't work, you can go ahead and comment/document it all you want, but that's not going to magically make it functional. Feel free to prove me wrong in that, but I doubt I'll be hearing from you again.
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 long as an API sticks to Init(), Get/Set/Execute/Calculate() and Deinit() it doesn't really matter, people will learn it sooner or later. What *does* matter, however, is that an API does not break "unwritten" conventions like always returning true even when the operation was unsuccessful (yes, I am looking at you Microsoft for that awful Windows Media Player COM interface - that was just evil!)
A picture is worth exactly 1024 words.
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?
"Focusing on style before functionality detracts the overall effectiveness of a program." "Let's just say, I would never hire you. Functionality should be completely mapped out before you even sit down to code." So you're saying that you wouldn't hire me based on the "counterargument" that functionality should indeed come first, which is what I said to begin with. Reasoning like that only comes from someone who happens to be a complete retard. You speak briefly of management and years of experience, yet fail to even begin your post in a cohesive, non-contradictory manner.
I wouldn't work for him. Years ago I worked for a manager who asked you to do specific things based on his understanding of what the company wanted (and he wouldn't give you the full picture), then when it turned out to be wrong berate you for doing what he said. Sounds a lot like this guy. Never again.
is that an API does not break "unwritten" conventions like always returning true even when the operation was unsuccessful
Most POSIX APIs return true on error and false on failure. The idea is that this lets you write if (something()) { error_handler(); }. I've no idea why they thought this made more sense than if (!something()), but judging by the rest of UNIX I suspect that they had to type their code in morse with one hand while fighting a tiger with the other, so every character saved could mean the difference between life and death...
I am TheRaven on Soylent News
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.
is that an API does not break "unwritten" conventions like always returning true even when the operation was unsuccessful
Most POSIX APIs return true on error and false on failure. The idea is that this lets you write if (something()) { error_handler(); }. I've no idea why they thought this made more sense than if (!something()), but judging by the rest of UNIX I suspect that they had to type their code in morse with one hand while fighting a tiger with the other, so every character saved could mean the difference between life and death...
I was under the impression that this was so that you could return an error code on error. It makes sense in that there are few values that evaluate false, just as there are few necessary variations on "function executed successfully", but there are many ways to screw something up.
Because that way there's only one success, and many failures.
0(false) = success
1(true) = failure
2(true) = different failure
3(true) = yet another failure
<xml><I><am><so><damn>Web 2.0</damn></so></am></I></xml>
On that tiger filled image alone you deserve every mod point available.
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
> Most POSIX APIs return true on error and false on success.
You were being funny but it comes down to granularity.
* For success you only need to know that it passed.
* If the function fails you want more details.
Here is an example:
Make sense?
Except that your example is actually really bad. The read() function in POSIX returns the number of bytes read on success, or -1 on failure and then sets errno to the value of the error.
I am TheRaven on Soylent News
Where are the mod points when you really need them?
Singularity: a belief in the "God" idea with the "demiurge" relation inverted.
That's not unfortunate, you're j-j-j-just h-h-h-handi-capable... very much
I wouldn't work for him either. Hell, if a manager isn't willing to give the development team a clear picture of everything that is needed, then they don't need to be a manager in the first place. Instead, they should be sending faxes and remedial officework. Unfortunately, in any industry, people tend to rise to level of their own incompetence.