4 ms·

For all the crap that Apple, Java and other open-source people have piled on Microsoft over the years, their developer documentation has always been very good.

For all the crap that Apple, Java and other open-source people have piled on Microsoft over the years, their developer documentation has always been very good. Yes, there are rough-edges. Back in the day, when Sun was still in-charge of Java, I had my 1-person consulting company partner with Sun and become an official "Certified Java" organization... Great, I thought - now I can get some better documentation... Sure, Sun replied - but first you have to buy a $30,000 server... Thankfully, .NET hit public beta about then and I have never looked back.

wlesieutre 6y ago
There's an old saying at Microsoft: developers, developers, developers, developers, developers, developers, developers, developers
- ethbr0 6y ago
  It's mocked, but the underlying observation is astute. In the personal computing world, first parties can't build enough user software. Furthermore, software availability and reliability lag third party developer and development ecosystem health. A bad experience doesn't hurt the platform today, it hurts the platform in 1+ years. And perhaps even worse, steps to address it take effect over a 1+ year timeframe as well. Apple's been able to leverage iOS market share into papering over the desktop reality, but they're going to find the emperor has no clothes real quickly if anything about that calculus shifts in a bad way.
  - jonhendry18 6y ago
    Apple used to be better about developers, I think, back 2000-2010 or so.
  - wlesieutre 6y ago
    Mocked at the time, but looking back it sounds pretty good. Maybe Apple needs a Steve Ballmer.
  - int_19h 6y ago
    If you recall, back when the first iPhone came out, the idea was that Apple itself would be the only provider of first-class software for it, and everything else was relegated to web apps. It didn't work out for them back then, and so we got native apps and the store. But I can't help but think that Apple still sees it as a sort of compromise of their ideal vision of what the platform should really be like, and thus dev ecosystem evolution is mostly on the backburner. Just look at how long it took for Swift to appear, despite Obj-C being really dated by that time.
sirmarksalot 6y ago
I wouldn't say it's always been very good. How well do you remember MSDN? In the mid-2000s, Microsoft documentation lived on three or four separate sites, and I don't remember the names of all of them. The two that spring immediately to mind are MSDN and TechNet. MSDN had the infuriating issue of broken links. You'd be deep-diving on an issue, find a link to an article that looked like it might perfectly address your question, and... 404. It got so bad that a VP ended up making a pronouncement, declaring a war on broken links. He announced a multi-year plan to reduce and eventually fix all the broken links on MSDN. This was the vacuum that was partially responsible for the birth of Stack Overflow.
- teh_klev 6y ago
  > It got so bad that a VP ended up making a pronouncement, declaring a war on broken links. Probably Scott Guthrie initiated that. As some nobody I once emailed him directly because I'd discovered a bug in some framework thing with a reproducible example. He actually replied and cc'd in the relevant people at MS and after a short while there was a workaround and a fix and a KB article or something (it's so long ago I barely remember). Impressed? absolutely. MS still have some pretty good and accessible folks, and I'm a huge fan of Scott Hanselman who's a great brand ambassador for DevDiv (and not beyond a few self-deprecating MS jokes about the company's past).
- bhrgunatha 6y ago
  They also suffered the same problem mentioned in this post. Documentation pages that showed a method's signature with no explanation of the function or example usage. So many times I'd look something up only to find the method name parroted as a full sentence; and those method names were often obscure to the point of meaninglessness.
- jjkaczor 6y ago
  Heh... well, I am old enough to remember the offline MSDN - which was great, and the rough transition to online - which got better, eventually... (and the rise of StackOverflow makes more sense in that context) but then at the beginning of the "cloud-era", IMO, it got worse again - to the point that I was constantly complaining about blog articles by MSFT employee's that really should have been folded into the actual documentation/KB instead... It's a hard sell to tell an IT decision-maker in a different team/group that you need to configure things "just so" (think TechNet versus MSDN for configuration/operational articles) when all you have to point them too is a non-official blog post... (Don't even get me started about the quality/out-of-date materials for things like Dynamics 365...)

wlesieutre 6y ago

There's an old saying at Microsoft: developers, developers, developers, developers, developers, developers, developers, developers

ethbr0 6y ago
It's mocked, but the underlying observation is astute. In the personal computing world, first parties can't build enough user software. Furthermore, software availability and reliability lag third party developer and development ecosystem health. A bad experience doesn't hurt the platform today, it hurts the platform in 1+ years. And perhaps even worse, steps to address it take effect over a 1+ year timeframe as well. Apple's been able to leverage iOS market share into papering over the desktop reality, but they're going to find the emperor has no clothes real quickly if anything about that calculus shifts in a bad way.
- jonhendry18 6y ago
  Apple used to be better about developers, I think, back 2000-2010 or so.
- wlesieutre 6y ago
  Mocked at the time, but looking back it sounds pretty good. Maybe Apple needs a Steve Ballmer.
- int_19h 6y ago
  If you recall, back when the first iPhone came out, the idea was that Apple itself would be the only provider of first-class software for it, and everything else was relegated to web apps. It didn't work out for them back then, and so we got native apps and the store. But I can't help but think that Apple still sees it as a sort of compromise of their ideal vision of what the platform should really be like, and thus dev ecosystem evolution is mostly on the backburner. Just look at how long it took for Swift to appear, despite Obj-C being really dated by that time.

sirmarksalot 6y ago

I wouldn't say it's always been very good. How well do you remember MSDN? In the mid-2000s, Microsoft documentation lived on three or four separate sites, and I don't remember the names of all of them. The two that spring immediately to mind are MSDN and TechNet. MSDN had the infuriating issue of broken links. You'd be deep-diving on an issue, find a link to an article that looked like it might perfectly address your question, and... 404. It got so bad that a VP ended up making a pronouncement, declaring a war on broken links. He announced a multi-year plan to reduce and eventually fix all the broken links on MSDN. This was the vacuum that was partially responsible for the birth of Stack Overflow.

teh_klev 6y ago
> It got so bad that a VP ended up making a pronouncement, declaring a war on broken links. Probably Scott Guthrie initiated that. As some nobody I once emailed him directly because I'd discovered a bug in some framework thing with a reproducible example. He actually replied and cc'd in the relevant people at MS and after a short while there was a workaround and a fix and a KB article or something (it's so long ago I barely remember). Impressed? absolutely. MS still have some pretty good and accessible folks, and I'm a huge fan of Scott Hanselman who's a great brand ambassador for DevDiv (and not beyond a few self-deprecating MS jokes about the company's past).
bhrgunatha 6y ago
They also suffered the same problem mentioned in this post. Documentation pages that showed a method's signature with no explanation of the function or example usage. So many times I'd look something up only to find the method name parroted as a full sentence; and those method names were often obscure to the point of meaninglessness.
jjkaczor 6y ago
Heh... well, I am old enough to remember the offline MSDN - which was great, and the rough transition to online - which got better, eventually... (and the rise of StackOverflow makes more sense in that context) but then at the beginning of the "cloud-era", IMO, it got worse again - to the point that I was constantly complaining about blog articles by MSFT employee's that really should have been folded into the actual documentation/KB instead... It's a hard sell to tell an IT decision-maker in a different team/group that you need to configure things "just so" (think TechNet versus MSDN for configuration/operational articles) when all you have to point them too is a non-official blog post... (Don't even get me started about the quality/out-of-date materials for things like Dynamics 365...)