in Search
Welcome to Neopoleon - Sign in | Join | Help
Navigation: Home | Forums | Galleries

MSDN Docs Totally Effing Suck Now - Windows Mobile API Reference - And... the irony of it all...

Yeah - that's right - I'm being hard on Microsoft, and some people think I'm doing it for attention, but... holy crapsticks... I've been easing back into geek stuff this past month, and I'm aghast - aghast, I say - at the lameness of what's happened in my absence.

There are a few of you out there who like to go around saying that I don't know a demmed thing about coding, but there are many more who remember the good old days when it was my life.

That's probably why I still regularly get emails about coding. I was turning people away for a few months, but I'm happy to help again. I've been emailed about every last bloody coding topic in the universe. I can't answer everything, but I like to help where I can. I took my public speaking job because I'd been that person emailing the questions so often, and, so often, the answers I got back were either crap or written in a dialect of English that only geeks speak and that's meant to obfuscate information to make the presenter of that information feel powerful. It's the insecurity of needing to appear intelligent. Drove me insane.

So, here I am, wanting to help. I used to focus on Windows Mobile development. I still love Windows Mobile. As you may have picked up, I've moved to the Apple camp, but I haven't moved away from WM. I still have half a dozen WM devices. The iPhone might be sexier, but WM is an amazing platform - especially if you're a dev.

In the old days, I helped people by being familiar enough with the .Net Compact Framework that I could answer questions far more quickly and in much less space than the docs could. Still, the docs were there, and they were great.

Were.

I had forgotten how much I hate the "new" MSDN. For years, I lived with MSDN in my browser. It was there all day - every single last effing bloody day. There were naysayers back then, and I couldn't understand. Compared to the docs for the other dev platforms from other non-MS groups and companies, MSDN was the absolute best reference tool I had the pleasure of using.

What happened?

A question came in about Windows Mobile last night. Sitting in a cafe right now, thinking it was going to be a simple five-minute job to get him the info he needed (he knows what he's doing, but, and probably because the docs are crap, there's a whole API he doesn't seem to know about that would solve all his problems).

Back with the real MSDN library reference, it was several clicks from the landing page to the hierarchical .Net Compact Framework API docs that made working with the platform the simplest thing. The answer to any question I had was, literally, seconds away.

I know the answer to this guy's question. It's been almost two years since I did any real WM .Net CF development, but I knew my stuff. The solution to his problem is in the .Net CF managed state API. The API is a little wonky, and there's a lot of info it can provide about the odds-and-ends of what's doing inside your WM device. Using the stuff is easy - the only real challenge is locating the members related to the state info you need.

But there's no easy way to find the docs. I took a look around, tried to drill down through the library the way I used to, but didn't find anything. My favorite part is that, at the end of the line where I thought I'd finally find the reference, there was nothing but a page with a link that takes you right back to the topmost layer of the hierarchy you've just navigated. Maddening.

I began looking for a general .Net CF reference. It was funny. The first result for a search for ".net compact framework reference" is titled, "Sorry". I love it. The next takes you to a page that links to the full .Net API reference. Thanks, guys - that's useful. What I want when looking for info is to trudge through the entire god damned API just to find something that might not even be there.

The third result for that search links to a book you can buy. There's nothing cooler than a giant expensive dead-tree version of what I used to be able to get for free.

Kept going, getting more and more specific with my googling.

Now... this is great. Seriously - I'm not sure anything more amusing could have happened here.

When I finally googled for "windows mobile managed state api" I got the bestest thing. I got the bestest reference out there.

I got me.

The search led to a screencast I did for Channel 9 back in June of 2006. And, holy shit, I just looked at the view count, and it's been watched 165,793 times. I'm famous. Woo-hoo!

That's interesting, though - if the docs were easy to find (provided they exist in the first place), do you think my screencast would have gotten so many views? That right there - the fact that I'm the first result for the information I was searching for myself - is a sign that something's seriously messed up out in MSDN Land.

Thank god for me. I'm going to go watch my own screencast so I can get this guy his answer.

The MSDN team ought to team up with the Windows Live Installer team to create a product so godawful that, to spare you from the pain, your head explodes in self-defense.

Taste the suck.

[Gratuitous Links to my Homies - Not Part of the Post Above] [Learn More]

- Robert Scoble - Robert and I made up recently. There were some things about an exchange we had last year that needed to be addressed. The reasons for my post (most of you probably have no idea what I'm talking about) were genuine, but the way I dealt with it was way out of line. Robert was on the receiving end of an especially bad week during my long rehab from the dr0ogs. Regardless of how disrespectful I thought his post was, he didn't deserve the treatment I gave him.

- Mini-Microsoft - Anybody who links to me demonstrates extremely good taste, and I like to promote that because I think it'll make the world a better place. Agreeing with me only makes you that much better than everybody else.

- Simon Murphy - You began with some commentary and a link to my post about the Windows Live installation experience, and the discussion in your comments section skipped right over it and went straight to an argument about how to pluralize "Lego" (Legos, of course). My kind of people. Solidarity, my brothas.

Published Saturday, March 01, 2008 3:16 PM by Rory

Filed Under: ,

Comments

 

Chris said:

I couldn't log into MSDN. I am selling my laptops as well as all my other worldly Canadian possessions before I leave:
http://search.ebay.com/_W0QQsassZnecro25
( please check weekly, there will be some awesome cheap stuff on there )
And when I went to go download XP,  which the Dell originally came with, but was wiped out upon arrival to install linux, the MSDN subscriber thing told me to screw off and gave me an error. I have to reinstall XP to sell it.
I paid over $1000 for MSDN pro, and this is the type of shoddy service you get. I googled it and realized that thousands of people can't log into their pricey MSDN subscription accounts. What a mess.
With Eclipse and the Google stuff there's really no need for MSDN anymore though right? I'm sure some people still use it, but it's getting obscure. I'm definitely not renewing.
March 1, 2008 4:37 PM
 

bart said:

I always thought MSDN was crappy when you weren't looking for something easy and common. Sources with comments+a tool to show you the class hierarchy are the force.
March 1, 2008 4:47 PM
 

Craig said:

As one of the guys who wrote the engine behind the new MSDN, you have my apologies. Although fortunately it sounds like your problem is with the content, not the content management system, so phew! :)

Anyway, I've forwarded your whole post to someone who might be able to do something about it. Maybe.
March 1, 2008 5:18 PM
 

Chris said:

Craig,

http://www.flickr.com/photos/8606487@N03/2303859484/sizes/o/
This is from 7 minutes ago.

I know I may not be Microsoft's favorite customer, but I still paid. It's been 2 days now. How about some service over here? How about the rest of the people that can't access downloads?

I barely ever use MSDN, but the once a year I do, I expect it to work. Ubuntu and Fedora plus Eclipse are up 24/7, and on 100 different mirrors and they're completely free. I'm not saying that to advertise for them, I'm simply saying you're totally outgunned if you're relying on the 1995 the only lemonade stand in town model.
March 1, 2008 8:12 PM
 

SDC said:

I have never really had a good experience with MSDN either.  Any good info I've had re: the Windows world of development seems to have come from some other poor schmuck who had a hard time sorting it out but had the decency to write about the solution once they found it.  I spent a couple of years honestly trying to like Microsoft, then backlashed hard around Vista.
March 1, 2008 8:15 PM
 

The Cowboy said:

I thought Google was the documentation for .Net
March 1, 2008 8:41 PM
 

Chris said:

"I thought Google was the documentation for .Net"
http://code.google.com/
http://code.google.com/android/
ect...

March 1, 2008 8:45 PM
 

Lloyd said:

I just got my WM device. Basically, I was excited.. and let down :(

http://lloydhumphreys.com/blog/?p=180

It's driving me mad :)

Also, when will you be getting messenger? Can't wait for a proper chat :)
March 2, 2008 5:36 AM
 

Massif said:

Ying Tong Iddle-Aye Po

That's all I have to say about that, I have deep sympathies with the documentation folks who create an astonishing amount of documentation for the ludicrous numbers of different APIs and technologies that MS churn out. But that's no excuse for not hiring a stack of technical writers to sort the whole thing out.
March 3, 2008 12:54 AM
 

Rory said:

Craig -

"As one of the guys who wrote the engine behind the new MSDN, you have my apologies. Although fortunately it sounds like your problem is with the content, not the content management system, so phew! :)"

The site itself is pretty - I've got nothing against the guts and the makeup.

It is, as you say, the content - it feels like I'm trying to look something up in a meatspace encyclopedia, but a couple volumes are missing. The pages themselves work fine - I'm just looking for pages with different words printed on them.

"Anyway, I've forwarded your whole post to someone who might be able to do something about it. Maybe."

I appreciate that - it was my hope that someone Up Yonder would do something (even if that something comes with an emphatic "Maybe").

Even when I was up in Redmond, I couldn't figure out who to talk to about stuff like this. It almost seems like the ideal solution is to fish for a response by writing a post. The lame part is that posts like this one irritate me - I don't want to be the whiny customer. But I also want to be able to, you know, like, find the info I need...

I'm going to try not to do these so often. I just sort of lost it when the WM content shuffled me around like it was a sassy Choose Your Own Adventure. Except that there wasn't really a choice - there was just a page that said, "Turn to page 93," and page 93 says, "Turn to page 124," and page 124 says, "Turn to page 93."
March 3, 2008 12:55 AM
 

Rory said:

Chris -

"I know I may not be Microsoft's favorite customer, but I still paid."

Did your subscription run out? It's been a while since I had an MSDN account, but, if I recall correctly, I was still able to log in after my subscription ran out - I just wasn't able to get the stuff I used to be able to get.

If that's not the case, then, yeah, I can see how this would be frustrating.
March 3, 2008 12:57 AM
 

Rory said:

SDC -

"...some other poor schmuck who had a hard time sorting it out but had the decency to write about the solution once they found it."

See... I'm trying to be that schmuck, but I can't. That's my beef.

It's not fair.
March 3, 2008 1:12 AM
 

Rory said:

The Cowboy -

"I thought Google was the documentation for .Net"

:)

I actually love MSDN - I mean, if I'm looking for regular .Net stuff, I think it's great.

But, in the old days, I wouldn't have had to google for what I needed. Plus, as I showed, googling for it only brought me back to myself :)
March 3, 2008 1:13 AM
 

Rory said:

Lloyd -

"I just got my WM device. Basically, I was excited.. and let down :("

It's funny - I've used many WM devices over the years, and I've always been happy, but I've also always known exactly which devices to get. Unless you're a hardcore WM nerd, there's no way to know what's going to be good and what's going to stink.

I'm so used to picking up the good ones and paying no attention to the others that I'd forgotten about the bad experiences people have.

I guess it's a lot like Windows Immobile in that respect - the OS itself is sound, but when you let an OEM get its dirty little hands on it, things crap out.

There can be four versions of pretty much the same hardware made for different carriers, and two of those four might be total duds. It's frustrating - as an enthusiast, I'd like to think there wouldn't have to be so many apologies.

There are many reasons for this, though. I won't name names, but some carriers receive hardware specs for WM devices and then cheap out on the components. There were a couple devices in particular that just *blew*. The customers blamed Microsoft, and the carrier pretty much did, too - but, had the carrier built the devices to spec, they'd have been great.

Blame is kind of complicated here now that I think about it... I wonder how tight MS's control is over WM device OEMs and carriers. It's not the same as the desktop - each device is the product of a *long* development process. You'd think everybody would be more careful.

It'd be like developing a new medication, just barely making it through FDA trials, and then swapping some ingredients out at the last minute for cheaper filling when it turns out the cheaper filling gives people brain-fungus-disease.

Nobody's happy in the end.

I was about to say that WM6 is a fantastic platform, but I'm not forgiving of MS when I encounter a problem that can most likely be blamed on an OEM - shouldn't be any different for WM.

So, I'm with you. If an OEM can't do a good job with WM, then MS should step in - *before* the thing goes to market.

Huh. I guess I'm blaming MS on this one...
March 3, 2008 1:25 AM
 

Rory said:

Massif -

"But that's no excuse for not hiring a stack of technical writers to sort the whole thing out."

It's becoming a theme.

Somebody at MS does great work, and then... somebody at MS does *no* work.

Or bad work.

Until Craig commented, I hadn't even thought to separate the MSDN platform from the content. It's another one of these MS's forty-third left hand doesn't know what MS's eighteenth right hand is doing problems...
March 3, 2008 1:27 AM
 

Lloyd said:

Yeah, I can't believe so many problems slipped in. To think - this is palms flagship WM product.

Unless I get a really good WM product to convince me otherwise (HINT people who're giving an xbox away to the kid who was duped) - I like the look on the new HP Enterprise thing, but I don't want to buy it if it's going to enfuriate me like my treo does - I reckon I'll be going back to Palm OS - simple, it works.
March 3, 2008 8:33 AM
 

Dana said:

I always had the same problem with sun's javadoc reference. It was fine if you already knew what classes and methods you needed to use, but forget trying to use the docs to find out how to do something. You'll spend hours tracing through class hierarchies, looking for an object that isn't abstract or one that has a non-abstract constructor.

My thought is that these large doc sets need to be split up into at least 2 aspects, by topic and by reference. There better be a larger intersection between the sets too, and it should be easy to flip back and forth between them using cross-referencing.
March 3, 2008 9:52 AM
 

Sjoerd Verweij said:

So you're complaining because they nuked the separate Compact Framework index?

Tsk tsk, picky picky...

I'd rather they spend some time fixing the LONG STANDING bug that hits you like a brick every time you install a documentation update (I'm looking at you, SQL Books Online): the Grand Unified Index gets nuked to the point that no matter from where you start the Document Explorer, that New Updated Content is now, magically, the One And Only content. No, really, all I need is the Infragistics documentation. I'll never need anything else.

*Grumble* *grumble*
March 3, 2008 9:55 AM
 

Ian said:

Chris/Craig/Rory whomever

There was an issue with MSDN subscriptions the other day, I couldn't download stuff either. I found if I clicked throught to product keys first, and then to downloads it worked, but following the (badly placed imo) paragraph to the right of the main screen that says 'current subscribers click here for downloads and product keys' or whatever it says caused a 'eek, we've got an error and its been logged'

it started working for a bit, then stopped, then started and seems to be fine now (at least it was this morning when I downloaded Server 2008.)

something broke, but not everything it seems.

Also, +1 for the confusing content layout etc. unless someone gives me a direct link to a kb article or whatever I dread having to search msdn these days. It's a shame, it used to be my goto place.
March 3, 2008 12:49 PM
 

Chris said:

"Did your subscription run out? It's been a while since I had an MSDN account, but, if I recall correctly, I was still able to log in after my subscription ran out - I just wasn't able to get the stuff I used to be able to get."

No, I still have 1 year left on it. It came back today and I was able to get the stuff.
Perhaps somebody reading this forum fixed my account. If so thank you. Even though you are a Microsoft heathen.

I am so happy today. I got an apt in a gated building complex for $800/mo. in long beach 10 mins away from the beach. That means I can spend hundreds on beer money a month. I rule.
March 3, 2008 1:30 PM
 

Rory said:

Dana -

"I always had the same problem with sun's javadoc reference. It was fine if you already knew what classes and methods you needed to use, but forget trying to use the docs to find out how to do something."

The sad this is that MSDN didn't used to be that way - it was easy to use to find whatever you were looking for. There might have been a little bit of a learning curve, but once you'd found something once, you knew how to find most other things. That's an accomplishment given the immensity if the site - so much content.

But my experience the other day sounds like what you're describing...

Java *is* a different story, though - MS had the benefit of starting with a perfectly clean slate, and most of the namespaces make perfect sense.

Java, on the other hand, has all these weird quirks and inconsistencies that make it tough to find things, docs notwithstanding.
March 3, 2008 4:30 PM
 

Rory said:

Sjoerd -

"So you're complaining because they nuked the separate Compact Framework index?"

Yep! Wooooo-hoooooo!

Lookitmego!
March 3, 2008 4:30 PM
 

Rory said:

Ian -

"Also, +1 for the confusing content layout etc. unless someone gives me a direct link to a kb article or whatever I dread having to search msdn these days. It's a shame, it used to be my goto place."

"Used to be my goto place" - that just about sums it all up. That's the bummer.
March 3, 2008 4:32 PM
 

Rory said:

Chris -

"If so thank you. Even though you are a Microsoft heathen."

*That* was funny :)
March 3, 2008 4:32 PM
 

Patrick said:

Holy cow rory.  You have no idea how right you are.

I recently had to look over policy configuration files on several different windows mobile devices.  This comment is going to be a doozer:

The policy xml files on windows mobile devices are ugly.  Policies are refered to by policy id and they output a value.  so you end up with some ugly xml that looks like this:

<wap-provisioningdoc>
- <characteristic type="SecurityPolicy">
 <parm name="2" value="0" />
 <parm name="10" value="0" />
 
 </characteristic>
</wap-provisioningdoc>

Now my task was to "figure our what these values mean and compare them across devices.   Let's ignore the amount of time it took me to find those resources.  Let's just say I eventually found the following:

http://msdn2.microsoft.com/en-us/library/bb416355.aspx
and
http://msdn2.microsoft.com/en-us/library/bb416273.aspx

Short version:  I had to look at each policy ID in the XML and then compare them to a poorly formated web page just to find out what each policy ID was.  So if I wanted to find out if the policy for remote api policies on a device, I had to remember that PolicyID 4097 was that one.  Oh, and then the policy values could be 0, 1 or a binary value that reflected the combination of multiple roles, much like a subnet mask.  That's the second url- the one that tells you your values.

So I had to compare 4 different OEMs for policy configuration, and the web pages I had just had tables of crap.  How did I go from ugly xml to something I could present to executives?

I HAD TO BUILD A FRICKING SQL DATABASE, RELY ON THE POLICY IDS AS PRIMARY KEYS, LINK THE "FRIENDLY" POLICY NAMES AND DESCRIPTIONS TO THE POLICY IDS AND BUILD A MODIFIED SUBNET MASK CALCULATOR TO INTERPRET THE VALUES OF EACH DEVICE'S PARTICULAR POLICY VALUE.  

This was just in order to make the documentation readable and applicable.

I realize that XML interpretation isn't meant to be a human medium- but I would have liked to see those who are creating the windows mobile policy documentation actually puting some thought into how someone may consume it.   Should I really be flipping between role documents and policy documents in order to interpret those special case values with the binary values?  Couldn't they at least include a hyperlink to the policy value possibilities in each policy row?  And at the VERY LEAST- if they're going to put us in these circumstances, couldn 't they use HTML that would cleanly cut and paste into excel column by column, row by row to reflect the formating they've intended?  If I could have just cut and paste, I would have saved at least an hour working on formatting issues thanks to copypasta problems that arise when you take from IE givith to excel.
March 4, 2008 6:52 PM
 

John said:

I owned those MW docs - well, the non-CF parts. I didn't hide them away though, that was the job of another team. What I did do was make a "shortcut":

http://msdn.microsoft.com/windowsmobile/docs




March 5, 2008 8:50 AM
 

Dana said:

Rory:
"The sad this is that MSDN didn't used to be that way - it was easy to use to find whatever you were looking for. There might have been a little bit of a learning curve, but once you'd found something once, you knew how to find most other things. That's an accomplishment given the immensity if the site - so much content."
I guess one of the sad things about our industry is that you can get something right, but only so long as nothing changes, or some nut doesn't wade through it swinging an axe.

"Java *is* a different story, though - MS had the benefit of starting with a perfectly clean slate, and most of the namespaces make perfect sense.

Java, on the other hand, has all these weird quirks and inconsistencies that make it tough to find things, docs notwithstanding."
My life is currently worse, because PHP's documentation makes me dream fondly of Java. I was just complaining about strcasecmp() and strnstr(), and these inconsistencies seem to have wormed their way through the whole thing *smacks head*.
March 5, 2008 10:51 AM
 

Lloyd said:

Are you trying to get on FakeSteve again :P
March 5, 2008 11:42 AM
 

Wayne Taylor (aka kryptos) said:

Thank you for that post, which I found this evening and is very excited that it worked but also that I now have to write a new app. :-)
April 30, 2008 5:32 PM
New Comments to this post are disabled

About Rory

I *own* this site, you loser.

This Blog

Post Calendar

<March 2008>
SuMoTuWeThFrSa
2425262728291
2345678
9101112131415
16171819202122
23242526272829
303112345

Post Categories

Feeds
Copyright Rory, 2008. All rights reserved.