Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Apple Developer Documentation Is Missing

v4.chriskrycho.com

Post reply on HN
Print view View original

351–360 of 400 posts

Re: Apple Developer Documentation Is Missing

#351

Post by userbinator »

moron4hire wrote: post #73
nullandvoid wrote: post #56

Earlier quoted context omitted.

I mean it's a discounted OS is it really a comparison? We're talking about one of the biggest platforms in the world here with unlimited money to throw at this problem there is no excuse

Seriously, Apple is one of the richest companies in the world (I don't remember if it's still The Richest or not). Similarly, Google's documentation is pretty bad, considering just how ludicrously rich they are. They could afford to hire entire teams whose only jobs were to write documentation and it would barely make a blip in their bottom lines. In contrast, I've always found Microsoft's documentation to be incredi…

MS has been great with documentation, but sadly in the recent years they've also been "outsourcing" a lot of the work to GitHub and relying on "community" to fix everything they broke in the horrid MSDN->docs migration. I use their docs daily, and I regularly come across stuff like this:

https://docs.microsoft.com/en-us/windows/win32/api/winsock/n...

Compare with the MSDN page which is surprisingly still there (if it isn't when you read this, check the Internet Archive):

https://msdn.microsoft.com/en-us/windows/ms741519(v=vs.100)

Or just plain misleading, like this function which definitely returns a value but has "void" in place of the actual type:

https://docs.microsoft.com/en-us/windows/win32/api/wininet/n...

The page on MSDN is correct as usual:

https://msdn.microsoft.com/en-us/windows/aa385098(v=vs.80)

I've also noticed a relatively huge amount of grammar/spelling errors in their newer docs, no doubt because MS has lost much of its real documentation team.

Fortunately most of my work with Win32 uses stable APIs that have been around since Win95/NT4, and thus are nicely documented in the infamous WIN32.HLP.

Re: Apple Developer Documentation Is Missing

#352

Post by userbinator »

mikestew wrote: post #110
moron4hire wrote: post #73

Earlier quoted context omitted.

Seriously, Apple is one of the richest companies in the world (I don't remember if it's still The Richest or not). Similarly, Google's documentation is pretty bad, considering just how ludicrously rich they are. They could afford to hire entire teams whose only jobs were to write documentation and it would barely make a blip in their bottom lines. In contrast, I've always found Microsoft's documentation to be incredi…

hire entire teams whose only jobs were to write documentation In contrast, I've always found Microsoft's documentation to be incredible. I don't know how Apple and Google work, but as a long-time-ago MSFT employee, I can tell you it is because they have entire teams. Chain-of-command, senior-level, leads, managers (don't know if there's such a thing as User Ed VP/Director, though) the whole works, like Microsoft kind…

I can fully believe MS had entire documentation teams, but looking at their newer docs, and much of what they've done with the old ones, it seems like those teams have mostly disappeared.

Re: Apple Developer Documentation Is Missing

#353

Post by jrumbut »

zapzupnz wrote: post #343
computerex wrote: post #325

Earlier quoted context omitted.

There are no examples.

There's no need for examples because initializing objects/structs is such a basic feature of both languages that Apple supports, it should be taken as read that the reader knows how to do it. CIColor.init(red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0) [[CIColor alloc] initWithRed:0.0 green:1.0 blue:0.0 alpha:1.0]

Need may be too strong a word, but I've never seen documentation suffer because there were too many high quality examples.

Great documentation uses those examples to shine light on other features that go nicely with (in this case) CIColor or to highlight the right way to do common tasks.

Re: Apple Developer Documentation Is Missing

#354

Post by rurp »

jrumbut wrote: post #353
zapzupnz wrote: post #343

Earlier quoted context omitted.

There's no need for examples because initializing objects/structs is such a basic feature of both languages that Apple supports, it should be taken as read that the reader knows how to do it. CIColor.init(red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0) [[CIColor alloc] initWithRed:0.0 green:1.0 blue:0.0 alpha:1.0]

Need may be too strong a word, but I've never seen documentation suffer because there were too many high quality examples. Great documentation uses those examples to shine light on other features that go nicely with (in this case) CIColor or to highlight the right way to do common tasks.

In addition to this, many developers (such as myself) learn best by example. Seeing a new tool in use is almost always the fastest way for me to grok it.

Re: Apple Developer Documentation Is Missing

#355

Post by jariel »

dillonmckay wrote: post #344
jariel wrote: post #323

Earlier quoted context omitted.

As someone with 'insider' insight into BlackBerry ... I would say the issue is complicated: 1) BlackBerry was never thought of internally as a 'platform' more of a 'solution' (i.e. you get what you get out of the box) - apps were a little secondary. That perspective was too slow to evolve. 2) The original Java APIs were not very well thought out - part of the problem in 'great docs' was that the underlying platform w…

Wasn’t there also an issue of allowing foreign governments to MitM their service? All the data was routed through Canada, right?

Yes, but that's an entirely different and complicated can of worms.

Due to its 'highly secure nature' it was sought after by individuals within regimes that had known surveillance and BB was way ahead of FB/Google in terms of attention by national powers around the world and having to 'deal with them' - at very least because it was actually used by entities in the first place! One of the drawbacks of Barack Obama using your device is that it's 'front and centre' and 'widely used' by every relevant 'agency' in the world.

It was a hugely difficult issue; hackernews tends to be 'anti state surveillance' in all forms - personally, I'm not as long as there's judicial oversight/applied properly (though sometimes it's not the case even in 'good' regimes) - the fact is basically every country you can think of wanted some type of special deal, the details of which I'm not at liberty to go into sufficed to say it was complicated on every level.

I can say however that Venezuela specifically was never going to get any help from us, and that BB was huge in that country due to it's effective protection from federal sources. Several countries like this were 'big blips' in sales due to the networking effects of this and other things. Penetration of BlackBerry around the world was very irregular, not like other platforms.

Re: Apple Developer Documentation Is Missing

#356

Post by WrtCdEvrydy »

dillonmckay wrote: post #344
jariel wrote: post #323

Earlier quoted context omitted.

As someone with 'insider' insight into BlackBerry ... I would say the issue is complicated: 1) BlackBerry was never thought of internally as a 'platform' more of a 'solution' (i.e. you get what you get out of the box) - apps were a little secondary. That perspective was too slow to evolve. 2) The original Java APIs were not very well thought out - part of the problem in 'great docs' was that the underlying platform w…

Wasn’t there also an issue of allowing foreign governments to MitM their service? All the data was routed through Canada, right?

Blackberry is a Canadian company.. but the general goals were to ensure all data was encrypted and no government would get access to it.

Re: Apple Developer Documentation Is Missing

#357

Post by jariel »

WrtCdEvrydy wrote: post #356
dillonmckay wrote: post #344

Earlier quoted context omitted.

Wasn’t there also an issue of allowing foreign governments to MitM their service? All the data was routed through Canada, right?

Blackberry is a Canadian company.. but the general goals were to ensure all data was encrypted and no government would get access to it.

"but the general goals were to ensure all data was encrypted and no government would get access to it."

Kind of, but not quite.

Little known history: BlackBerry 'became encrypted' because back in the days when it was really just a 'pager with email' - North American carriers (channel partners) were actually reading BB executives emails during negotiations (!!!). BB discovered this and decided to start with the encryption. Seriously - the first 'illegal' act was by BB customers/channel partners!

From there, it was always pragmatic. BB was never specifically motivated by protecting individuals from governments persey.

Re: Apple Developer Documentation Is Missing

#358

Post by devin »

As someone who has only recently gotten into producing an app for iOS, I was immediately struck by the lack and quality of the docs. It’s nice to hear that I’m not alone.

The lack of documentation led me to feeling like I was just somehow personally missing something. I’ve been at this for awhile and the apple docs left me feeling like a junior programmer all over again. I wanted to first blame myself, but it’s become clearer to me that Apple just doesn’t care about supporting devs. That’s the theme for years now and it only seems to be getting worse. Bummer.

Re: Apple Developer Documentation Is Missing

#359

Post by ethbro »

kbenson wrote: post #315
mikestew wrote: post #110

Earlier quoted context omitted.

hire entire teams whose only jobs were to write documentation In contrast, I've always found Microsoft's documentation to be incredible. I don't know how Apple and Google work, but as a long-time-ago MSFT employee, I can tell you it is because they have entire teams. Chain-of-command, senior-level, leads, managers (don't know if there's such a thing as User Ed VP/Director, though) the whole works, like Microsoft kind…

I winder how much of Microsoft's focus on documentation and having full teams to produce it was also spurred by the nature of their enterprise business and the whose ecosystem of certification and training it supported (which in turn supported Microsoft in a cyclical nature). Microsoft has a whole set of of official test prep and training material, certified trainers, etc. Even if the documentation department never m…

It also likely traces back to support.

In that Microsoft has it, Google doesn't, and Apple... magic?

But if you're going to run a competent support org, you need to have high-quality, easily-accessible documentation. Because you're not going to know anything about {insert random thing support ticket is asking about}.

And if you've already created those docs for internal use, why not simply make them public?

Re: Apple Developer Documentation Is Missing

#360

Post by grogenaut »

jimbokun wrote: post #273
grogenaut wrote: post #194

Earlier quoted context omitted.

As someone who does a lot of interviewing at a big company, by the time the candidate is in a room (virtual or real) with me large amounts of vetting has been done by managers and recruiting. I really only look at the resume for context if I even do at all. I'm there to cover a specific technical competency and soft competency, and any other data I can get in 45 minutes + bio break, make feel comfortable, and them as…

Throw out everything else you are doing in those 45 minutes and just look at their repo and make a decision based on that. You'll get better results. (Maybe spend a few minutes on the phone just to verify they are really the person who wrote all that code.)

Guess you missed what I meant. The manager/recruiter covers that. If it's substantial then I would likely get called in to review it.

The on site interviews are checking for things like communications, soft skill, design, etc. Things that don't fully come across in a code repo and are hard to verify who did what.

We have tons of people who try and misrepresent themselves. It would be a waste of time for the 6 people on a loop to all read the repo. It would also be bad if we didn't cover the things we cover in the on-sites.

We are also required to keep loops the same for all candidates. So giving an offer to one candidates because they have a GitHub repo and a phone call and the rest don't and therefore have to come in is a no-no. Therefore they all come in.

Post reply on HN