I notice Microsoft regularly breaks its own developer URLs as well... even the links from within Visual Studio's help system to their online content. It's sad that the most reliable way to find documentation is through Google.

MSDN is a mess, so much so that at a previous employer we setup our own MSDN server and hacked it up with a wiki, we mirrored entire sites, including Sysinternals and Windows Developer Journal and the DDK sites; MS specially fucked this company up so bad, in other respects as well, that the teams were warned against adopting any new Microsoft technologies; we stuck to raw ODBC and NT driver model, even for Vista.

Or you could install it locally... The installed MSDN library is rock solid. I've yet to find an instance of the online docs being better.

When I have used online help in visual studio, the worst problems I experienced were some formatting issues.

Ideally, this shouldn't happen anymore; or, at least they've designed the current system to stop it from happening: http://msdn.microsoft.com/en-us/magazine/cc163845.aspx

Incidentally, Google tends to break CPAN's documentation a lot. If I visit the "canonical URL" for a module, something like http://search.cpan.org/perldoc?Foo::Bar, it always works. If I google for Foo::Bar, though, sometimes I get linked to http://search.cpan.org/dist/Foo-Bar-0.17, which is 404 because the author deleted version 0.17 and uploaded 0.18.

Amusing that other people have the opposite problem.

You can't delete anything from CPAN.

I've never experienced what you describe.

You can actually. I can’t find a link now, but I’m pretty sure it’s actively encouraged so as not to clutter up the CPAN with obsolete versions of modules.

That’s why we have things like http://backpan.perl.org/

... Or bing. Maybe it's a deep rooted conspiracy to get you on bing. Or not...

It’s not like this is even exclusive to the documentation—every new release of OS X takes over /macosx (or whatever it is).

It seems like somebody involved feels that there’s no use for the past.

That would be Steve "we don't need no stinkin' floppies" himself.

Yeah, I've seen this several times. I don't know how they put the site together, but it doesn't sound like it would be a hard problem to solve.

As weird as it is on the web, it's even weirder in their developer tools. I kid you not, there are HTML files in "/Developer/Documentation/DocSets/com.apple.ADC_Reference_Library.CoreReference.docset/Contents/Resources/Documents/documentation/Cocoa/Reference/ApplicationKit/Classes/NSApplication_Class". Whereas, if they'd hired me to do it, I would have probably called it "/Developer/Documentation/Cocoa".

While absurdly long, that path actually does (mostly) make sense. If you were to do it, it would be an organizational mess when looking for something.

/Developer is the standard install path. Documentation/ for docs, DocSets for the actual docs (as opposed to sample code), com.apple.ADC_Reference_library to say its an ADC reference library (as opposed to installing your own docsets, which some libraries have), CoreReference.docset to say which docset it is exactly (leopard vs snow leopard, for example), Contents/ is pretty standard for OS X bundles, Resources/ since docs are technically resources, Documents/ (again, there are other files here: sample code, tech notes, etc), documentation/ for the documents themselves, Cocoa/ for which framework you're looking at (It could also be Carbon, Webkit's CSS, Darwin, Java, etc), and, well, thats the end of the chain on my system. But to continue it based on a guess, Reference/, possibly redundant, but its nice for organizational purposes, ApplicationKit/ - you are looking up something in AppKit, but there are other *Kit's that can be used as well, Classes/ instead of headers, maybe, and then NSApplication_Class for the class that you want.

The structure is consistent with other bundles. But the question is, are bundles really the logical way to handle documentation? I don't think so.

If you look in places like "/Library/Application Support", everything is basically broken down by product or vendor. It is hard to imagine having so much documentation installed that similar naming wouldn't suffice for DocSets.

Apple has also used saner documentation layouts elsewhere (and oddly, in places that are probably not meant to be "public" documentation). For instance, there's a /Library/Documentation, and its layout is very easy to follow.

Quick request: Do you think you could put 2 spaces in front of the long url so that it doesn't distort the page layout. That way people will only have to scroll to see the url, and not the rest of the page. Thanks!

I wish I'd done that earlier, but I only thought of it after the editing window (2 hours?) was gone. I can't fix it now...

Indeed. They need someone to go through and give nice urls to all of their documents. Also be good for someone at 1 infinite loop to get a list of all the old urls, and map them to the new urls.

Probably not a hard task for their web team.

In my more paranoid moments I think Apple is actively trying to make it difficult to develop for their products. I know how crazy it sounds but it's not entirely irrational.

I mean, how can a company that puts so much effort into perfectionism do something like this by mistake?

I don't know which URLs are broken, but I don't have a hard time finding docs from Apple. I rarely view docs based on a URL another dev passes along. We usually trade advice like "check out the UIViewController doc" or "read the Threading Programming Guide" instead. In an ideal world the URLs would be consistent and concrete, but they're really secondary in this particular culture. I think you're making a mountain out of a mole hill to be paranoid about it.

It's a culture thing. Steve created a much more ambivalent relationship to external developers than the usual love affair most tech companies strive for.

Microsoft has always been about the ecosystem, for Apple third-parties are always a threat to a smooth user experience. When the video driver on your mom's PC crashes, does she blame Nvidia who wrote the code or Windows?

You make an excellent point. Given the low quality of the driver ecosystem, I'm amazed that most Windows machines function at all. ATI, Creative, and Silicon Image are at fault for 90% of the BSODs I've ever experienced.

messy kitchen, exemplary dish

You can Search for anything in the Developer Documentation (installed with XCode).

This isn’t about that. I link to Apple’s documents in my blog posts, manual, mailing list replies, tickets, etc.

It is extremely frustrating that these links break with time, not made any better when then users write me to tell that my links are broken.