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.
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"
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.
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.
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.
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.
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".
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
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.
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>
> 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?