> 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’t done.
Apple has enough rabid supporters, they can lose the occasional developer to bad docs. Apple doesn't care or need to care. They are arrogant that way. Also, what other platforms? Android? A fair portion of iOS devs are also already Android devs.
Look, this is just going to fall on deaf ears. Apple isn't listening. Their machine is output only.
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.
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 wasn't very good to begin with.
3) BlackBerry was a tiny company compared to Apple and Google. When BB launched maps, there was no 'mapping team'. There were 0 people dedicated to mapping. G had I think more than 100 at the time, just dedicated to that. BB was growing rapidly, but had found itself jammed between Apple and Google - two of the most magnificent and well capitalised companies in the world.
I'm still amazed that BB had all the features it did given how small the teams were. Most of the handheld - hardware and software - was developed in one little building - you could literally know everyone working on it personally if you worked there.
3) All of that said - the docs were not that bad. Everything was technically documented. The support teams were decent, just small.
"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.
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.
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.
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.
I'm not the person, but I had an HN leaderboard member pitch a tantrum at me about a programming opinion on here, and imply that my opinions were representative of my employer. It's a good reason to stay pseudonymous.
Another good reason, and a good reminder that popularity, status and/or power does not automatically rid a person of the human foibles that plague us all.
Ah, that's true, good point. As someone that has mentioned more than enough information to definitively identify myself online with this account, I guess I've adjusted enough that I didn't even consider that.
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 incredible. It can often be hard to find the right thing (though that has getting better, though that might be just my growing experience on how to find things), but they put real, actual effort into documentation.
Also, Microsoft has a very strong "corporate style guide" for API design. Every MS API within their major silos is built exactly the same way as every other API. Once you've had some experience with them, it's easy to figure out the others. I find Android to be down-right schizophrenic in comparison.
It's one of the many reasons I continue to focus on MS platforms for my work. It's been 20 years since they were the hostile "kill everything that moves" company that people lament.
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 kinda took it seriously or something. Hence my ranking of docs:
1. Microsoft: could be better, but you're going to have an easy time finding worse. No, they're actually pretty damned good. When I worked there, for instance, there was a big push that example code will be secure. The mantra was "sample code becomes production code". APIs have close-to-real-world examples of usage. "Could be better"? Eh, I don't know what I'd improve, frankly.
2. Back before they got really big, I'd say about Apple's docs, "does the job; it's not Microsoft-quality, but they don't have Microsoft resources, now do they?" Umm, that's not true anymore, and I think the quality has gone down since.
3. Google: just use Stack Overflow. The docs are just going to frustrate you with their incompleteness and outdateness.
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.
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?
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.
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:
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.
Most developers who are making apps for iOS are working for companies that only care about money. There is no fanaticism about it. If developers optimized for working on platforms they liked, no one would write console games.
Um, hmmm, that is exactly the opposite of my experience writing console games. Console game dev is fun because you can push the machine to the limit and know every technique you use will work across all devices since they are all the same (or close enough). PC/Mobile dev is hell compared to that. I worked at a company that did mostly console, shipped one PC game, vowed never again as the support costs were several orders of magnitude higher than console.
Isn't that the exception that proves the rule though? Why is Twitter the most effective way to get developer support from Apple as opposed to their own website?
Yeah. As much as I appreciate their responsiveness on Twitter, it doesn't much help those of us who are not on Twitter.
(Tangential rant: I dislike how it seems like the most effective path for anything resembling customer service from many companies is to call them out on Twitter alone. I've written emails to some companies over months to no single response—but to look on their Twitter you'll see an answer within hours, or minutes.)
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.
> 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.
Yes, pretty much every company is this way. I often get a response, support ticket and solution via Twitter before my email/webform request is even processed.
tl;dr: Recent performance improvements in the Mac version of Firefox are dependent on an undocumented feature of an API that was tweeted out by someone from Apple
Taking bug reports on Twitter is nice, but not comparable to improving documentation.
One is a developer reaching out (costs: developer time, management involvement: granting permission). The other is a change in project plans, staffing, workflow and timelines (costs: large, management involvement: massive).
>> One is a developer reaching out (costs: developer time, management involvement: granting permission). The other is a change in project plans, staffing, workflow and timelines (costs: large, management involvement: massive).
I think it's a pretty safe bet to expect, for this reason alone, that the documentation quality of things like SwiftUI will improve over time. It seems pretty obvious they directed all their efforts to releasing SwiftUI within their iOS 13 release window, which likely meant the API only 'stabilized' very late in the process and it would be impossible to spend time and resources documenting it, at least not without postponing the release (not an option).
Generally speaking, in my experience all of the 'established' Apple API's have pretty good documentation. SwiftUI seems rushed, and it would probably been better if they waited until iOS 14 and release it along with documentation. I'm not definding Apple here, but I think the article is overstating how bad their documentation is based on one brand-new API that probably wasn't fully cooked for release to begin with.
These is just a very small subset of incidents with Apple where Apple failed to right their wrongs and was ultimately forced to do so by public and or legal pressure. Apple as a company is known for ignoring feedback altogether.
> Your point being? I said nothing that is contradicted by your comment.
You said this in reply to the parent:
> I don’t know how you convinced yourself that Apple is more interested in being aloof than in making changes that would help them make money but that belief is just as ridiculous as the belief that they are altruistic.
I gave many examples of Apple not willing to make changes to improve user experience. There are many more examples that I haven't yet mentioned.
Apple has enough rabid supporters, they can lose the occasional developer to bad docs. Apple doesn't care or need to care. They are arrogant that way. Also, what other platforms? Android? A fair portion of iOS devs are also already Android devs.
Look, this is just going to fall on deaf ears. Apple isn't listening. Their machine is output only.