Hacker News Reader

Comment by psahgal | Hacker News Reader

Has anyone else noticed that Apple has been slowly moving away from the long-form guides that were helpful at explaining core concepts? I remember once seeing a comprehensive guide on code signing, but over the years it appears to have been scrubbed from their documentation resources. In its place is a much less helpful (but prettier-looking) guide.

In comparison, I've noticed Android has FANTASTIC developer documentation. I've found full guides for everything. Even esoteric classes that are rarely used have at least a little bit of documentation.

View on HN

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 APIs, the latest being notifications, which according to my coworker had 3 full revision, and finding documentation for the last one is hard. Storage (with Android 11 modifications) is another place where the documentation is starting to get stale. Those are not the only APIs were the documentation was poor.

In my opinion, Android documentation is at the same place iOS documentation was about 5 years ago (before they started removing entire pages from the documentation) : overall very good, but a few places were it's not up-to-par or downright horrible. I don't expect the quality to improve in the future.

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.

Yea, i think that's correct. documentation is just another product, no different than other software. so basically you can start asking with very common user reasearch questions such as: * who would use our documentation? * what would our user need the most from our documentation?

I feel like Android 11 is in a weird spot. Its a covid release and they didn't have their IO convention this year either. Seems like a lot of the big documentation dump is harder to find.

I wonder if this is on purpose and that some companies receive good documentation so that competition is kept at bay. Does Google offer some sort of training packages for Android or you can get a loan dev that knows all the quirks? I've seen this with other companies where documentation is poor on purpose so they can make extra money from training.

I don't think Google does consulting or specialized training like this for Android.

For Google Cloud Platform, they partner with other companies (like the one I work for) to help with GCP setup. This partner program was started in the last few years, so I don't think they were doing this for Android back when Android development was new.

Also, the company I work for spent a lot of time building Android apps for Fortune 500 companies, so I feel like I would have heard about it. Our clients would have benefitted from having Googlers build Android apps and train people!

I'm seeing notifications as a feature fail on my android phone too. Apparently there is simply no reliable way to get a notification at a particular time (e.g from a todo app) anymore. ON A PHONE. THE THING DESIGNED TO BEEP/RING/NOTIFY YOU OF THINGS.

Because of all the junk they've added re: battery optimization, "Adaptive AI" notifications. Even after disabling much of that, it takes a 3rd party app to get notifications reliably.

Sure there are. I get one every day from my alarm clock 5 minutes before it starts yelling at me.

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" that is basically just the function name with added spaces between words.

There are good reasons to hide the implementation details in documentation. The primary being it’s easier to keep the documentation up to date, our primary topic here. Many languages even publish class interfaces but not necessarily implementation details.

That said, a couple of example code snippets on using the interface wouldn’t hurt.

> The primary being it’s easier to keep the documentation up to date ...

That's NOT a "good" reason in any sense.

That's a terrible reason, which no-one in a team leader or above position should ever sign off on.

We're going to have to agree to disagree on this one. But let me give you all an example.

Wolfram Documentation on Mathematica is excellent in my humble opinion. Here is a function I use very often, convolve.

https://reference.wolfram.com/language/ref/Convolve.html

Notice how the interface is very well described, there are examples on how to use it, but there are no implementation details.

Your reference example includes lots of details, examples of usage including source, explanation of options, etc. :)

That's not an "easier to keep documentation up to date" type of thing ;), but is definitely an example of good documentation.

Unlike the Apple approach mentioned above. :( :( :(

Following that reason, the easiest way to keep the documentation up to date is to not have documentation.

It’s always the null cases that get you... I suppose if “up to date” was the only requirement I would agree. But in reality there are many competing requirements which is why there are many degrees of documentation. Obviously internal and external documentation will be different too.

The reason to keep implementation details out of the docs is that people will rely on those implementation details, and then when their app breaks, they won't even think of looking at the documentation for updated implementation details. After all they probably have the old version all but memorized, and the app may break in a way that isn't obviously related to the implementation that changed.

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 a need for more and better documentation, but some pointy haired boss in upper management seems to think the current situation is fine.

Current situation is, money is coming in. Stock market still loves apple. So for them it seems fine.

Basically. What are you going to do? Not release your app on apple devices? No, you will do whatever it takes to work it out yourself.

It might even be in their interests to drive away all but the most dedicated developers. After all, they have more apps than they'll ever need, the problem is always quality.

> the problem is always quality

But writing quality apps requires quality API documentation. I don't know how developers fumbling around in the dark can result in quality apps.

Being "dedicated" to Apple platforms is not the same as being dedicated to quality.

I would struggle to get many things done if not for that one particular Apple engineer and their forum posts.

We all would. Eskimo is a treasure and I have no idea how he does what he does.

When I worked at Apple in the mid 90's, DTS had to hire someone to go around to every engineering team to collect what they had change so we could write a tech overview of an OS release, otherwise no one would have known what changed. But then was when Apple was going out of business.

I once owned every copy, of every generation of "Inside Macintosh."

I agree about the Android docs.

However, in defense of companies that don't like to have too much documentation around, I can tell you, from personal experience, that writing developer docs is hard, as is doing developer support.

Keeping them up to date is also a challenge.

I call it "concrete galoshes": https://littlegreenviper.com/miscellany/concrete-galoshes/

I was a Mac beta tester back in '83, and still have a copy of the pre-release "Inside Macintosh" mimeographed the day after the original programmers wrote their drafts, filled with penciled in corrections and in some places pages of hand corrected notes. Reviewing a formal copy after edition 2 or 3, I was surprised to see a reduction in information quality and some of the key information from the penciled in notes completely missing.

That is a cool story.

I got my first Mac in '86 (a Mac Plus).

My first copy of Inside Macintosh was the hardcover. I think it was two volumes, back then.

The original Inside Mac was 3 volumes, after their initial printing of the "phone book edition" - all three volumes in one thick soft spine binder. I really need to take the time to scan my copy and put it online. It's got ballpoint pen corrections from the Apple Engineers telling the beta testers various fixes.

Yes, and this is a really shame. Several years ago I was able to become an iOS developer almost completely by reading through Apple's docs and then building a couple of projects on my own. I had a checklist of the programming guides to work my way through from Objective-C, to App Programming, to view controllers, and on. Over the years I found it more and more frustrating to truly understand new frameworks as the documentation changed. iOS development is now a small portion of my job and the lack of good resources is making it hard to stay up to date.

This. Their documentation on CoreAnimation concepts was wonderful [1]. It even has these little appendix sections discussing advanced use-cases.

Sadly, they seem to have stopped writing these at around 2015...

[1] https://developer.apple.com/library/archive/documentation/Co...

Relevant username?

The long form guides are great, but for much of SwiftUI they're even missing the most basic 3-line summary of what a thing is.

I so often need to do a simple thing, find a function that looks about right, and the documentation for it says literally nothing about how to use it.

My guess is they’re realized documentation is a huge cost center and even their own technical writers are overburdened by the churn of deprecating APIs and changing best practices. It’s worse then the JavaScript community.

I find this business decision fascinating because a good portion of their App Store revenue comes from developers. One would THINK developer relations would be a priority at Apple, but it's pretty clear that's not the case.

It was one of things that I found unbelievable when switching from Android to iOS development. The developer experience is just so much WORSE on iOS. Sometimes, it's as if Apple is actively trying to annoy developers.

They have such a strong market presence and so much power, they don't have to care for the moment because developers will come to the platform anyway.

"documentation is a huge cost center"

It's a tiny cost center, in the grand scheme of things. As it is they probably spend less than they spend cleaning the glass at Apple Park.

For API documentation, if you can specify what you intend to build well enough to build it and validate that you have built even approximately what you intended to build, documentation shouldn't be much more work.

And even when there's no documentation, or when it isn't enough, you can just always dive into AOSP sources and figure out whatever needs to be figured out. They've recently made this more convenient too: https://cs.android.com

No such luck for iOS. Best you can do is poke at binaries with a disassembler.

I have been frustrated many times after stepping into a system function on iOS, only to be greeted with a mountain of assembly instructions. It was one of the first grievances I had with iOS development, coming from Android.

On the other hand, it's been a great opportunity to learn how ARM works!

If you haven’t tried Hopper already, it’ll level up your reversing skills: https://www.hopperapp.com/

I'm curious who maintains the Android docs. Is it all open source? Is any of Apples?

Based on the Android source code I've seen while working on Android projects, I think a good portion of the Android docs are generated by the inline documentation from the Android open-source project.

But on top of that, Google also produces high-quality long-form guides. Those are first-party guides, found at https://developer.android.com/. (Google maintains the Android developer site.)

Ah ok, thanks for the response! I've seen a lot of value in automatically generated docs from inline code. Perhaps that's a key baseline strategy for improvement.

Add then padding that with the long-form guides with concepts and examples.

Oh yes, I remember the programming guides! When a friend of mine and I wrote the text editor Tincta we spend days to go through the typesetting, font, glyphs documents. We didn't really use it but we learned so much (we were still students and couldn't imagine how complicated all that is). Same for the maps and location APIs. You could really appreciate all the work and design that went into the APIs.

Now I feel some of that information is hidden in WWDC videos but it's not the same.

I also had good experience with the Android documentation, same (as the article stated) for PHP and most of Microsoft.

Only if you happen to follow Android team developers on Medium (it used to be G+) and Twitter.

The documentation has lots of outdated stuff that only gets updated across Medium, StackOverflow, bug tracking comments, twitter posts, /r/androiddev.

https://en.wikipedia.org/wiki/Inside_Macintosh Guess these days are over...

Reply on news.ycombinator.com