On Apple's Piss-Poor Documentation

Re:On Apple's Piss-Poor Documentation by Fradow on Tuesday November 10, 2020 @11:35AM (#25047843)

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.

[ Parent | on HN ]

Re:On Apple's Piss-Poor Documentation by psahgal on Tuesday November 10, 2020 @11:41AM (#25047911)

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.

[ Parent | on HN ]

Re:On Apple's Piss-Poor Documentation by dwiash on Wednesday November 11, 2020 @12:20AM (#25055709)

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?

[ Parent | on HN ]

Re:On Apple's Piss-Poor Documentation by hutzlibu on Tuesday November 10, 2020 @02:07PM (#25050041)

"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.

[ Parent | on HN ]

Re:On Apple's Piss-Poor Documentation by intricatedetail on Tuesday November 10, 2020 @12:59PM (#25048882)

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.

[ Parent | on HN ]

Re:On Apple's Piss-Poor Documentation by psahgal on Tuesday November 10, 2020 @02:25PM (#25050421)

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!

[ Parent | on HN ]

Re:On Apple's Piss-Poor Documentation by jayd16 on Tuesday November 10, 2020 @12:58PM (#25048868)

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.

[ Parent | on HN ]

Re:On Apple's Piss-Poor Documentation by zaptheimpaler on Tuesday November 10, 2020 @10:45PM (#25055302)

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.

[ Parent | on HN ]

Re:On Apple's Piss-Poor Documentation by Dahoon on Tuesday November 10, 2020 @11:08PM (#25055415)

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

[ Parent | on HN ]