OMG, their docs for certificates and profiles doesn’t match error messages or xcode or their dev site where you manage them.
:/
On Apple's Piss-Poor Documentation
171–180 of 348 posts
Re: On Apple's Piss-Poor Documentation
#172Have you considered using Qt? It compiles and runs native on macOS, the documentation is superb. You just let the Qt people worry about the Cocoa, Quartz etc. interface. As a bonus, it will also run on Windows, Linux, Android, iOS. Qt looks like an "operating system". It isn't really an O/S, it feeds off the underlying O/S, but to the applications programmer, it completely subsumes the O/S. We converted a 500KLOC Win…
I can always tell when I'm using a Qt app on my mac, because my keyboard navigation shortcuts don't work
Re: On Apple's Piss-Poor Documentation
#173Earlier quoted context omitted.
A trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.
It's not really the size of the company. Anyone qualified to write good documentation can make better money, work on more interesting things, and advance their career by actually working on the code. Without a culture that rewards and values the work it doesn't get done.
Well, not everyone who is qualified to write good documentation wants to work on the code, nor would they necessarily be as good at writing code as they are at writing documentation. If you're writing API documentation, you need to be enough of a coder to understand what the engineers are talking about -- and what they aren't talking about but really should be! -- but that doesn't mean you need to be coding at a level where you could have a career writing apps built on that API, let alone coding at a level where you could have a career implementing the API itself.
It's the "culture that rewards and values the work" that's really the issue, I suspect. Apple certainly used to have a culture of good documentation, and I know they've hired good writers, technical and otherwise, over the years. It's actually kind of difficult to explain why their docs are the way they are, other than just not putting any real priority on the necessary work.
Re: On Apple's Piss-Poor Documentation
#174Earlier quoted context omitted.
Android HAD fantastic documentation, just like Apple had 7/10 years ago. It might not be overly apparent just yet to everyone, but Android documentation is slowly following the same path as Apple documentation, where the experience is slowly degrading, but since it was so good a few years ago, that degradation didn't creep everywhere just yet. My coworker and me are already starting to feel the pain on various core A…
Even 5 years ago, I felt that Apple's documentation was way worse than Android's. I wonder if there is a good way to measure documentation quality...I suspect such measures will require techniques borrowed from user experience research.
"I wonder if there is a good way to measure documentation quality"
I would start with a checklist:
- is it complete and consistent
- is there a description to every important piece
- working examples
... and if this is complete, you can measure all you want, but I would start with the basics.
Re: On Apple's Piss-Poor Documentation
#175Earlier quoted context omitted.
A trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.
Just hire Microsoft's people. Not even joking. https://docs.microsoft.com/en-us/dotnet/api/system.string.su...
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.
Re: On Apple's Piss-Poor Documentation
#176I agree with this completely.
Apple recently required that anyone using 3rd party authentication (google, fb, etc) in their iOS app, must also provide support for Apple ID signin. That is not an unreasonable request. I was able to implement the signin without too much difficulty. However, when it came to doing a server-side validation of the signin via the Apple API; it was an absolute POS blackbox.
Their documentation and server responses provided no indication of why the validation failed. I searched the docs and forums; it was clear that a ton of other people had the same problem with absolutely no clues into resolving the issue. So I just gave up on it. Total waste of time.
Re: On Apple's Piss-Poor Documentation
#177Earlier quoted context omitted.
Yes! Apple used to have Technical Notes that were a deep dive into how the OS is implemented. They were super helpful in troubleshooting and optimizing for Mac OS. They haven't published anything like this in over a decade. I suspect someone took "hiding implementation details" too seriously, and now Apple never talks about how anything works (it's all magic). You only get function's signature, and "documentation" th…
The other day someone referenced this post by an Apple engineer: https://developer.apple.com/forums/thread/663858 Why in the world is this a random undiscoverable post in the (terribly designed) developer discussion forums rather than a Technical Note in the documentation? It would have been a TN in the past. In fact that same engineer wrote a number of old Apple TNs. It's clear even to some within Apple that there's…
Current situation is, money is coming in. Stock market still loves apple. So for them it seems fine.
Re: On Apple's Piss-Poor Documentation
#178Marco is right about PHP's documentation. I've felt for a long time that the quality documentation PHP provided played a major role in the language's success.
It's true! For me, PHP's docs were an amazing on-ramp to becoming a developer "I just need a function that does something like...". A lot of the language design is annoyingly inconsistent and hard to use, but even in 2005 there were clear explanations on how to make it work.
As an experienced engineer, if I'm handed a well-designed but poorly-documented API, I can usually guess the intent and make it work, at the cost of working more slowly. But a junior engineer will be completely stymied by insufficient docs, regardless of how good the software design is.
I guess, in summary: good docs can make up for bad code. But good code can't make up for bad docs.
Re: On Apple's Piss-Poor Documentation
#179I don't think Steve would have allowed this to happen. Developers are way too important part of the whole "where the money comes from?" question. He would have noticed the complaints before anyone wrote a blog about it. iOS docs were great back in 2011.
Docs for the 68k Mac were abysmal. There was a collection of books entitled "Inside Macintosh" that were nearly impenetrable, and only scratched the surface of the elaborate class libraries. Instructions for creating "Hello World" on the Mac were dozens of pages long. From what I've read, Jobs certainly understood the importance of software, but only great software. He didn't want the Apple ecosystem to become loaded…
I still have my copies of Inside Macintosh, I consider them to be examples of good documentation.
They didn't cover "class libraries". I don't have copies of whatever documentation was provided with MacApp, I do have a Think-C manual that describes their environment.
Re: On Apple's Piss-Poor Documentation
#180Earlier quoted context omitted.
PHP's documentation is amazingly well done. It goes above and beyond almost everything else.
PostgreSQL’s documentation is also amazingly well done. There’s also HighCharts. But not the documentation, rather the fact that I almost never felt like I needed any. The API was just so well done that you didn’t need any. That was my experience anyway.
in the old days MySQL + PHP became a popular combination because they both had great docs. But Oracle has let MySQL's documentation get worse and it's no longer the best