Apple Developer Documentation Is Missing • Hacker News Board

Re: Apple Developer Documentation Is Missing

#311

Post by canada_dry » Mon, Oct 28, 2019, 9:35 PM UTC

WrtCdEvrydy wrote: post #28

chooseaname wrote: post #9

> Apple, if you want developers to love your platform — and you should, because good developers are your lifeblood — and if you don’t want them to flee for other platforms — and you should be worried about that, because the web is everywhere and Microsoft is coming for you — then you need to take this seriously. Adopt the mentality that has served other frameworks and languages so well: If it isn’t documented, it isn…

It's really funny to think about cyclical stuff and see how Blackberry used to treat their developers like shit (with stupid signing keys and stuff) and just look at Apple falling into the same trap.

When speaking to Blackberry execs (10+ yrs ago) about their abysmal developer support I pointed to apple.com/developer as an example of how it should be done. Blackberry's lack of developer support was surely one of the key reasons for its failure.

Apple seriously needs to re-focus.

Re: Apple Developer Documentation Is Missing

#312

Post by scarface74 » Mon, Oct 28, 2019, 9:36 PM UTC

FpUser wrote: post #302

scarface74 wrote: post #238

Earlier quoted context omitted.

Well. An opinion about something “being a status symbol” should be able to come up with some basis in fact. By definition, a “status symbol” is something that you buy to show that you have more “status” than the majority of people because you can buy something that most people can’t. If the majority of people can get a product, how can it be a status symbol?

>If the majority of people can get a product, how can it be a status symbol? Simple. If you have it you're ok. if not you are a marginal

But seeing that the other 50% don’t have iOS devices, how can they feel marginal?

Re: Apple Developer Documentation Is Missing

#313

Post by kbenson » Mon, Oct 28, 2019, 9:39 PM UTC

throwaway_symb wrote: post #168

craydandy wrote: post #42

Earlier quoted context omitted.

And this reminds me of the documentation quality of Symbian around 2005-2007. I would highly recommend the author of the article the check it out, before lamenting Apple's documentation.

The Symbian documentation team was tiny, perhaps 20 people at most. At an offsite we would pretty much fit round two tables at most. As always you get what you pay for. Even so the Symbian team did some pretty cool things such as creating open source documentation standards for C++ and the tools to support that. Source: I was there.

Honest question: What's the purpose of the throwaway account for this? Is there some blow-back that you expect from this? Is there some NDA that precludes you from even talking about it years later? Do you think it reflects negatively on your years later?

Re: Apple Developer Documentation Is Missing

#314

Post by novok » Mon, Oct 28, 2019, 9:47 PM UTC

Apple under invests in developer tooling relative to what it does. The dev tooling teams are surprisingly small and the internal dev experience at apple for their own employees is pretty bad compared to other large tech companies. My guess partly is because of the siloed nature of the company, and they don't sell dev tooling for "money".

Re: Apple Developer Documentation Is Missing

#315

Post by kbenson » Mon, Oct 28, 2019, 9:50 PM UTC

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 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 made a profit themselves, I imagine being able to point to some revenue and it being an important part of the overall business strategy kept it as feeling fairly important to most execs.

Re: Apple Developer Documentation Is Missing

#316

Post by sosborn » Mon, Oct 28, 2019, 9:51 PM UTC

52-6F-62 wrote: post #287

revscat wrote: post #275

Earlier quoted context omitted.

I get what you're saying -- that companies should be internally driven to address concerns such as yours -- but I'm starting to shift away from that thinking. We're social apes. We evolved in groups, and respond to group pressures. Responding to public shaming is perhaps a more natural state of things than what we tend to expect. It certainly seems more effective.

It's the dirty road, though. In capitalism the market is supposed to correct for bad acting like poor customer service. Instead it's a public haranguing like putting someone in the stocks, except in exponentially less response time.

> In capitalism the market is supposed to correct for bad acting like poor customer service.

That only works when the public knows that the customer service experience is poor. I'm no fan of Twitter, but putting this stuff in the open is incredible effective for this reason.

Re: Apple Developer Documentation Is Missing

#317

Post by kbenson » Mon, Oct 28, 2019, 10:02 PM UTC

oefrha wrote: post #180

andybak wrote: post #78

Earlier quoted context omitted.

> usually for a function like “setReturnVectorFlag” it’s just sets the return vector flag. Ah - the "repeat the method names with spaces in it" style of documentation. This is merely an exaggerated form of a trap that the majority of documentation falls into to some degree - documenting the "what" but neglecting the "why" or "how". It tells you the bit you can easily work out by intuition, reading the source or using…

> Ah - the "repeat the method names with spaces in it" style of documentation. That's usually a symptom of aggressive linters enforcing the rule that every single public method must be documented. Programmers then produce useless "documentation" to shut the linters up. Utter waste of disk space.

I can see that as possible, and I can also see how it might very negatively impact a documentation drive on accident. One of those things that sounds good, and could be beneficial, but when enacted without strong guidance just ends up combining with culture or human nature to make things worse. E.g. a rule that says there must be documentation, but without standards and enough review to make sure that it's good documentation. Stats show things getting better, but that's because we always drift towards optimizing what we measure, which is not always the same what we actually want.

Re: Apple Developer Documentation Is Missing

#318

Post by pfranz » Mon, Oct 28, 2019, 10:02 PM UTC

uwuhn wrote: post #289

pfranz wrote: post #228

Earlier quoted context omitted.

I was at a place that had been around for 20+ years, but needed to grow fairly quickly. So they systematized their hiring process. The focus was on generalists both because a lot of their technology was written in-house (it predated the commodity, off the shelf, solutions). It used the theory of the off the shelf solutions, but often had a different name or a slight difference. But the major reason they wanted genera…

Do any specific interviews come to mind? I'm curious what sort of questions you asked, since I am a specialist :)

This was all about 10 years ago and it definitely lifted some of the trends with interviewing at places like Microsoft, Google, etc. There were 3 areas; technical, personality, and critical thinking. The criticism I noticed from interviewees grew further down that list. The job involved user support, which was the personality portion (it wasn't just "team fit"). Critical thinking had some of those abstract, problem solving questions tech companies were notorious for, but also had a mix of actual issues encountered.

Here's my defense for the critical thinking questions since I know it's a contentious topic here; I'm evaluating how they asses and troubleshoot something. Often, actual technical problems get caught up in the minutia or domain specific parts. So abstracting it and even removing all of the tech keeps people from getting hung up on that. I hate "trick" questions, but sometimes would ask one to see if they were thinking towards optimization or non-traditional. It's actually deflating if they already know the answer. I never cared if they got a result, I'd often move on if it took too long.

I felt the most criticism towards the technical questions. Many of them were more technical than really ever came up on the job. I think it's good to find the limits of a candidate's knowledge, but not ding them for it. An example would be doing stuff with pointers when the job is 100% in a scripting language. Sure, ask them if they know the basics of pointers, sure maybe once in 5 years they'll troubleshoot a bug that might need obscure knowledge, but I would hope that would get triaged and passed around instead of expecting everyone to deal with the 1% case.

Re: Apple Developer Documentation Is Missing

#319

Post by CharlesColeman » Mon, Oct 28, 2019, 10:12 PM UTC

kbenson wrote: post #313

throwaway_symb wrote: post #168

Earlier quoted context omitted.

The Symbian documentation team was tiny, perhaps 20 people at most. At an offsite we would pretty much fit round two tables at most. As always you get what you pay for. Even so the Symbian team did some pretty cool things such as creating open source documentation standards for C++ and the tools to support that. Source: I was there.

Honest question: What's the purpose of the throwaway account for this? Is there some blow-back that you expect from this? Is there some NDA that precludes you from even talking about it years later? Do you think it reflects negatively on your years later?

>> The Symbian documentation team was tiny, perhaps 20 people at most. At an offsite we would pretty much fit round two tables at most. ... Source: I was there.

> What's the purpose of the throwaway account for this?

My guess is they want keep their other account pseudonymous, and admitting that they were one of a specific team of 20 people at a specific company goes a long way towards unambiguously identifying them. At a minimum, one of their teammates could probably ID them.

Re: Apple Developer Documentation Is Missing

#320

Post by jariel » Mon, Oct 28, 2019, 10:14 PM UTC

Absolutely true: if it's not well documented, it's not a product, it's borderline useless. Apple is just one of many 'big companies' that strangely under-document so many products, frankly it's bizarre.

If you don't have good docs, tutorials and snippets, it's not 'done'.

iOS, Qt, many frameworks: spending days, sometimes literally weeks writing 'tiny experiment code' to navigate the ambiguities or missing parts of docs, it feels totally unacceptable to have to do this.

This is a hugely important statement the author is making.