if developer_docs == bad then app_quality = bad; Coders slam Apple for subpar API manuals

Sorry state of documentation baffles programmers as iGiant launches new MacBook Pros, promises better keyboards

A man reading a bad document

Apple developers are becoming increasingly vocal about their displeasure with the state of the iGiant's programmer documentation, which they depend upon to craft iOS and macOS software.

In a blog post on Monday, macOS developer Michael Tsai makes note of a handful of fellow coders expressing discontent with Apple's instructions for working with its technology.

Among them, Scott Anguish, a veteran developer who used to work at Apple, observed on Twitter that old iOS documentation has been moved into an archive and is now unsupported.

"There seems to be no modern guidance for, say, [text fields] blocked by keyboards," he continued, referring to the challenge of dealing with a virtual keyboard on-screen that obscures an underlying text interface element. "I can’t fathom that this can be the case."

"You can’t write apps without authoritative docs," he elaborated.

In an email to The Register, Tsai said he didn't know why Apple's documentation is in such a poor state. "There really isn't much visibility for those of us on the outside," he said. "Apple does seem to be introducing new and changed APIs at a faster rate, so there is likely more work to be done. But it's not clear why they can't hire enough people to keep up or why they're hiding or discarding the older documentation that hasn't been replaced yet."

Developers care deeply about technical documentation because inadequate or inaccurate explanations contribute to errors and project delays. When Mozilla partnered with Google and Microsoft in 2017 to improve the web programming how-to guides hosted by the Mozilla Developer Network, the goal was to improve the development experience through more consistent and cohesive documentation. Mozilla as it happens was named developers' favorite source of documentation in SlashData's Developer Choice Awards 2018 Digital Edition.

For Apple, subpar documentation raises the likelihood of subpar apps from developers and makes its software platforms less hospitable.

Anguish's complaint elicited replies from a number of other developers facing similar frustrations.

"The amount of issues in their docs is astounding," said software developer Charlie Fish.

Tony Arnold, lead developer at Itty Bitty Apps said, "Apple’s developer docs are dreadful right now."

"I'm so glad I'm doing Android development now," said Heath Borders, a mobile developer at Twitch. "I really don't understand how [Apple] could let documentation languish like this."

"As far as I can tell, this is the only documentation on [In-App Purchase] receipt validation," observed Steve Tibbett, a developer who works for Adobe. "This is part of a current system that's making Apple billions of dollars. There are errors in it, and it's 'no longer being updated.'"

fortnite

A decade on, Apple and Google's 30% app store cut looks pretty cheesy

READ MORE

Tibbett added that he's going to wait until after Apple's Worldwide Developer Conference in June to complain since there may something bigger going on.

If so, that may have something to do with Apple's Marzipan Project, a new interface SDK for writing apps that run on both iOS and macOS, which presumably will require some new documentation. Also, the ongoing shift from Objective-C to Swift has added to the challenge of keeping docs up to date.

Tsai however said he doubts the Marzipan transition can be blamed. "This has been going on for a long time, and Marzipan is not going to replace the need for the documentation that's missing today," he said.

In Apple's developer forums, there have also been a handful of complaints about the state of developer docs over the past year. "The online documentation of the Apple frameworks is often out of date," a developer wrote back in November. "With Swift 3 (released Sep. 2016) the new DispatchQueue classes were introduced. The documentation at developer.apple.com offers little information about the functions and properties of these classes."

Complaints of this sort date back further still:

The Register asked Apple to comment on the complaints about its documentation. We don't expect the iPhone maker will reply.

Tsai agreed that Apple could be more responsive, particularly with regard to its Radar bug reporting system. "I have not had good luck getting responses or fixes to the Radars I file, documentation or otherwise," he said. ®

Sponsored: How to get more from MicroStrategy by optimising your data stack

SUBSCRIBE TO OUR WEEKLY TECH NEWSLETTER




Biting the hand that feeds IT © 1998–2019